Version 2 Documentation and GitHub Pages

[multimeric]

We've already started some discussion on documentation for version 2 on slack: https://nancyfx.slack.com/messages/documentation/

I think we've reached the conclusion that we should make a github pages site, which might be a good idea for attracting newcomers to Nancy. We've decided to put the github pages docs inside a docs directory in the main repo (and not to use a separate gh-pages branch) as markdown files. Finally, we've decided that the docs should have separate sections for each major version (currently, 1.XX and 2.XX)

We haven't reached an exact consensus on the static site generator to use and I'd love some input on that. I'm proposing something like MkDocs: http://www.mkdocs.org/, where we edit the docs, and run mkdocs (a python script) to update the static website files, and then we commit the original markdown and generated files each time we want to commit a change to the documentation. The alternative is using Jenkins, which github automatically runs, meaning we don't have to commit the static files at all, and we only need commit the markdown files. The downside of Jenkins is that most templates/themes are designed for blogs, not documentation, so we have slightly less choice if we go with Jenkins.

I produced a proof of concept github-pages website for Nancy here: https://tmiguelt.github.io/Nancy/. This was made using Jenkins and it's a bit unfinished (it doesn't have the entire documentation in it, for starters) but it should demonstrate the value of having the docs on a website rather than just in the wiki.

So what I'm asking is:

1. Do I have the go-ahead to start working on the docs? I don't want to put in a lot of work unless it's likely that we'll use a system like this. One of the admins would have to enable github-pages in order for this to work as well
2. What static site generator should we use? I've presented MkDocs and Jenkins, but the dev team might have other preferences?

[nandotech]

Just dropping by to volunteer my services

Interested in contributing to the project, and helping document can also help teach us while we teach others! :)

Plus. I'm sure @jchannon @thecodejunkie and rest of team would gladly welcome all the documentation writers who willfully subject themselves to this type of thing.

[cemremengu]

Reinforcements have arrived! Count me in for the effort.

[multimeric]

@thecodejunkie raised a very valid point, which is that our documentation system should not require extra steps:

here's a good measuring stick Does it require any additional manual steps other than accepting a pull-request? => :fire: anything else would mean adding additional ceremony that is not required if we just stay on the wiki

So this means that either we use Jenkins for the site, which by definition is no-ceremony since GitHub pages runs the build, or we integrate the gh-pages build into our current build process, which would automatically build the markdown and presumably commit it to the gh-pages branch. I'd love some input from the devs on how easy this would be to do.

[xt0rted]

Recently they updated this so you can use the master branch instead of gh-pages. If you put everything under /docs it should publish from there every time a new change is pulled in. https://github.com/blog/2228-simpler-github-pages-publishing

[multimeric]

@xt0rted Yes and like I said in the first post this is definitely a better way to handle things. However if we end up having to do the documentation build separately (on a CI server for instance), it should probably stay in a separate branch since it would only ever be committed to by the server

[multimeric]

However, given the need for low-ceremony docs, I would be happy to use a Jenkins theme such as any of the following (remember we can reskin them as much as we like):

• jekyll-docs-template: GitHub | Demo
• docslate: GitHub | Demo
• documentation-theme GitHub | Demo

[xt0rted]

What I meant was if everything goes under /docs then it'll use Jekyll to build the site so there's nothing more to setup or do beside accepting the pr (once the initial config is in place that is). Unless I'm misunderstanding something this is exactly what we're looking for.

[multimeric]

Yes it is, and I mentioned Jekyll as an option. However it's not the only option, and the problem with Jekyll is that there are very few themes that have documentation in mind. They exist, like the 3 I just posted, but most of the Jekyll ecosystem seems to focus on blogging

[jchannon]

Also have to consider versioning. We may want docs for v1 and docs for v2

On Wednesday, 19 October 2016, Michael Milton notifications@github.com wrote:

Yes it is, and I mentioned Jekyll as an option. However it's not the only option, and the problem with Jekyll is that there are very few themes that have documentation in mind. They exist, like the 3 I just posted, there are limited options.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/NancyFx/Nancy/issues/2588#issuecomment-254673672, or mute the thread https://github.com/notifications/unsubscribe-auth/AAGapmhOHDPwx7YEHq-ySTsNvkby6MjDks5q1V3vgaJpZM4KZzio .

[thecodejunkie]

@jchannon simple, we're sticking them in sub folders

[multimeric]

Yes, but I still don't like the idea of having the version 1 docs in the version 2 branch. Technically the docs should be tied to the code in the same commit as them, so for any commit that you check out, you have up-to-date docs without any irrelevant information.

If we did this, then we could make our github-pages site only show the docs from the master (which would be 2.XX), and link to the docs on GitHub for the 1.XX branch if they needed then. Which wouldn't be on a pretty website but at least we don't have redundant information in our repos.

Just a thought

[thecodejunkie]

I disagree. It's just, again, adding unnecessary complexity to something that's not really a problem in the first place

/documentation
  /1.x
  /2.x

Is perfectly fine. It's going to come down to the burden of maintenance. Say we find a problem in the 2.x docs, which also needs changing in 1.x .. if we used branches and what not then it would be a PITA to fix it (branch checkouts, multiple PRs and so on) vs. just fixing them both side-by-side in a single commit. I'm perfectly fine with ending up having duplicates of stuff. I.e when we go to create the 2.x docs we'll simple take a full copy of 1.x and make the appropriate modifications even if that means most files will be identical in both 1.x and 2.x

Anything else would just be too tedious. Having some sort of "shared" content and then content which are unique to a specific feature is not maintainable in the long run either. Let's keep it simple and let's fight our instinctive need to solve problems, which does not exist yet, with over complicated solutions 😄

[multimeric]

That's not true at all! If you find an issue in both 1.X and 2.X, someone will need to write a commit to patch it. They simply branch off the 1.X branch, fix the bug, and update the docs (in the docs directory). Then they merge this fix branch into both 2.X and 1.X, and voila everything works. The docs in each branch are now up-to-date, and the github pages (which are running off the master/2.XX branch) will be updated as well.

With your method, the person writing the commit patch has to update the 2.X and the 1.X docs in their fix, and then when they try to merge the 2.X docs fix into the 1.X branch it will try to create the 2.XX docs which they'll have to delete because they don't belong there but that were introduced by the fix. All that because we have a redundant copy of the docs in our repo.

My method is even simpler:

2.XX branch
    /docs

1.XX branch
    /docs

[thecodejunkie]

I'm not talking about a code bug (we're not updating the 1.x code branch anymore, it's in code freeze), I'm talking about an error in the documentation.

[multimeric]

Hmm. If you're not updating anything, even documentation in the 1.XX branch, I suppose there's no way to have docs in that branch at all. So I guess we might have to store 1.XX and 2.XX in master. That still bugs be though.