We used to have our documentation hosted on gitbook.com, written in markdown. They have since moved on to a different format and restrictive team sizes. We need to find another place to host our documentation.
After some experiments with mkdocs in https://github.com/IMA-WorldHealth/odk-documentation, I think we can probably accomplish the same thing (or better) with plain old github pages. We would put our documentation in our /docs folder and be able to update it in each Pull Request that changes the functionality. This would be built and deployed using Jekyll.
To my mind, the advantages of this method is:
Free hosting!
Easily change relevant portions of the documentation when you change the functionality. It makes it clear to describe what changed in the same way that tests do.
No need to redirect contributors to a new mechanism for contributing documentation changes. BHIMA contributors can contribute to documentation improvements, directly in the source code.
We used to have our documentation hosted on gitbook.com, written in markdown. They have since moved on to a different format and restrictive team sizes. We need to find another place to host our documentation.
After some experiments with
mkdocs
in https://github.com/IMA-WorldHealth/odk-documentation, I think we can probably accomplish the same thing (or better) with plain old github pages. We would put our documentation in our/docs
folder and be able to update it in each Pull Request that changes the functionality. This would be built and deployed usingJekyll
.To my mind, the advantages of this method is: