The wiki-as-submodule pattern
User documentation for your software project is important.
But, beyond it taking time to be written, two main points make it hard to have a good manual:
- You can never guess all subtleties your users will encounter, thus it needs regular updates based on feedback.
- It gets out-of-sync with code.
A way to help with the first aspect is to host your documentation on a wiki.
This way, all your users can contribute and improve it, without needing access to the codebase, nor a formal approval process. Anyone discovering a mistake or simply a misleading phrasing can correct it easily.
This is why GitHub projects all provide a wiki by default: they decrease the cost of writing.
This comes at a cost, though: increased cost of reading. For yourself, as updating a documented API element means first opening up a web application and searching for all pages that reference it. And for your users, as you'll quickly need to add version indications to your doc for it to last.
Acknowledging these, many projects include user documentation directly as files in their code repository. That ensures any doc state is consistent with any given version of the code, and makes all documented symbols (preference keys…) appear in the documentation when searching for them within the codebase. This helps documentation to stay up-to-date, as a refactor can not miss it.
So, the available options seem to be either use the power of the crowd and ease of edition to maintain your doc, or integrate it properly with your code.
These two options don't need to be exclusive, though: simply use a wiki, and include its data within your codebase. You get the best of both worlds: user-contributed updates when you want them included, search-and-replace within code AND docs, and versioning handled by the VCS, making doc snapshots a breeze.
And the best part is, this is extremely easy to do if you're using Git & GitHub. As mentioned above, all projects get a wiki. And this wiki is itself a Git repository of Markdown documents.
Thus, you can simply include it as a submodule of your project, and have all the benefits listed above:
git clone git@github.com:USER/PROJECT.git
git submodule add git@github.com:USER/PROJECT.wiki.git doc
git submodule init
git commit -m 'Add docs from GitHub wiki'
