I'm not totally happy with using the Wiki as the official documentation and I would like to move the documentation from the Wiki to the actual QATrack+ repo. In addition, I would like to move to using Restructured Text instead of markdown as the markup language. From my perspective some of the pros and cons are:
- ReST is quite a bit more sophisticated than markdown (also a con) and can generate nice table-of-contents etc.
- Switching to ReST will allow us to use the nice standard Python documentation tool Sphinx
- Sphinx has multiple output targets including HTML & LaTeX (which can then generate pdfs)
- Putting the docs directly in the repo will allow us to host our documentation on readthedocs.org which is free, attractive and has lots of nice features (including integration with bitbucket)
- readthedocs.org allows us to tightly couple the documentation to the QATrack+ version which will become increasingly more important. Not everyone will be on the same version all the time and I'm worried the docs will start to get muddled with respect to versions. You can work around this in a wiki, but I really like being able to tie doc versions to git tags & branches.
- Raises the barrier somewhat for contributing to the documentation.
- ReST is a bigger and more confusing/arcane markup format than markdown.
Feel free to comment if you have any thoughts :)