What is the best way to publish a programming tutorial on Github?

Question

I would like to publish a series of programming tutorials along with some code on github. The tutorials will be written in markdown. There will be several markdown documents with references to each other.

Now I wonder what would be the best option:

1. Put plain markdown files into the repository, together with the code
2. Use the github wiki for the tutorials and link to the code
3. Use github pages (e.g. with jekyll) for the tutorials and link to the code

I am not very familiar with github pages nor with the github wiki, so any hint about (dis)advantages in this context is helpful!

Answer 1

You have mentioned three different ways you can go about doing this, I'll elaborate on each of them...

Markdown files in repository

This method isn't actually too bad, because its possible for people to contribute to it as long as they know Markdown (and Markdown is very easy to learn anyway) as they simply need to send off a pull request after forking your repository. Also, since Github uses something called Github Flavored Markdown you can embed the code directly into each file and have some nice looking syntax highlighting.

Github Wiki

Using the Github wiki is a feasible option because it will make it easy for other people to contribute to it. However, you may prefer to have changes made by other people on a approval type system, this is when you'd go with the first option because of the pull requests feature. I personally wouldn't recommend that you use the wiki purely because it undermines the Github repository itself (having an empty repository with heaps in the wiki). This is just my personal opinion though.

Github Pages generator

You could use the Github Pages generator and make a website using that. However I would like to point out that it uses Jekyll to generate the site, and that the generator will only create one page automatically, the rest of the pages will be up to you to make using Markdown and a bit of HTML. It will look nicer, but it will be much more time consuming.

My personal recommendation

I recommend that you have the tutorial itself hosted in a Github repository written in Markdown, and then you can create a page using the page generator that will link to all of the parts of the tutorial (acting as a landing page)