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?