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 WebsiteA Github WikiMarkdown Files Hosted On GithubPlacing All Docs in Github README.mdThe 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?
How to manage an open source project's documentation?
open source;documentation
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 toolThe 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