Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

closed as too broad by gnat, MichaelT, Robert Harvey, Jim G., Kilian Foth Oct 28 '13 at 8:49

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

While I do not really have an answer, I came across this blog post on managing documentation with the github wiki. cach.me/blog/2010/12/… You may find it useful. –  jschoen Jul 14 '11 at 18:55
add comment

4 Answers

up vote 5 down vote accepted

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

share|improve this answer
In my opinion, documentation that is generated from source files is necessarily but rarely sufficient. Adequate documentation must always include copious non-trivial examples as well as a step-by-step tutorial. Also, documentation that is generated from source code is only as good as a documentation embedded in the source code. –  Adam Crossland Jul 14 '11 at 19:33
I didn't mean auto generated from the code. I mean't that if you are putting an explanation of what a function does, it has to be next to the function or it doesn't get updated. You can still put a intro documentation in a separate intro.h. This is especially important for a library where you need accurate per function docs –  Martin Beckett Jul 14 '11 at 20:28
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
would you mind explaining more on what it does and why do you recommend it as answering the question asked? "Link-only answers" are not quite welcome at Stack Exchange –  gnat Oct 26 '13 at 22:43
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.