I am the creator of a growing open source project. Currently, I\'m becoming frus

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?

Explanation / Answer

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

Related Questions

Navigate

• Browse (All)
• Browse I
• Subjects

Integrity-first tutoring: explanations and feedback only — we do not complete graded work. Learn more.