Third-Culture-Software / bhima

A hospital information management application for rural Congolese hospitals
https://docs.bhi.ma/
GNU General Public License v2.0
220 stars 105 forks source link

Host BHIMA documentation out of the /docs folder #3438

Closed jniles closed 5 years ago

jniles commented 5 years ago

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:

  1. Free hosting!
  2. 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.
  3. 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.
  4. Powerful themeing and plugins using Jekyll.
  5. We can host the documentation at our install sites relatively trivially - just install Jekyll and compile!
jniles commented 5 years ago

This is live as of #3481.