How to manage an open source project's documentation?

Question

I am the creator of a growing open source project. Currently, I'm becoming frusterated trying to figure out the best way to manage documentation. Here are the options I have considered:

• HTML Website
• A Github Wiki
• Markdown Files Hosted On Github
• Placing All Docs in Github README.md

The documentation is already written in Markdown, I just can't figure out how I want to make it available. I'm really drawn towards Git since I can branch and tag the documentation just like I can branch and tag the source.

I could use a Markdown library to translate the Markdown to HTML and display it on a styled website. I would need to upload changes to the website anytime there was a change, and it would be difficult to manage all of the different "tags" of the documentation.

Github Wikis (as far as I know) do not change according to the branch you are on. So, I could only have the "master" version of the documentation in Github Wiki form at any given time.

Putting it all in the Github README is kinda neat. I get branching and tagging, but it's a little tiring to use and doesn't lend itself well to easy navigation.

Am I missing some awesome solution? What other options do I have?

Answer 1

One thing I would say is the documentation MUST be in the source code files (using whatever markup you want) and then docs generated automatically from these.
At least on your site, you can generate formatted downloads of the docs as part of the source package so the user doesn't need a specific doc tool

The chance of somebody else fixing/adding a function and then editing/adding a bit of markup documentation immediately adjacent in the same file may be low BUT the chance of them finding a completely different file in a different document repository to do the same are slightly less than zero.

You can always have a tutorial.h that contains big blocks of text if your want - but treat it as part of the source

Answer 2

If your project is a library, nothing beats javadoc-style documentation to document the API syntax from comments within the code itself.

As for the documentation on tutorials, usage examples, etc. I highly recommend using a wiki format. Other projects I've seen have separate pages for different branches. When you start a new branch you just copy over the things that haven't changed to a new page and update from there.

My reason for recommending a wiki is anecdotal, but from personal experience. I have contributed documentation updates to open source projects on several occasions, but they have all been on wikis. If I'm trying to figure something out and the documentation is misleading or unhelpful, after I figure it out I will update the wiki while I'm in the docs and it's fresh in my mind. If not out of a sense of giving back, at the least because I know I'm likely to need to look it up again myself in a year or two.

If there isn't a wiki, the barrier to entry is just too high to bother, between figuring out how the documentation is generated, where it's stored, getting the latest from source control, how to make edits, making the actual edits, and navigating the mailing lists to get a patch accepted.

If you want tight control over your documentation, by all means use whatever is most comfortable for you, because you'll mostly be the only one updating it. If you want to encourage community participation, use a wiki.

Answer 3

If you don't mind converting the docs from Markdown to reStructuredText, consider Sphinx . It's just as easy as markdown, but it's a lot more powerful.

Answer 4

Markdown Files Hosted with the source works extremely well.

The RST-based docutils tools, for example, can create HTML or LaTex (and PDFs) from one set of documents.

This -- in effect -- combines your option 1 and option 3.