Friday, April 14, 2017

New documentation system

The Institute for Disease Modeling is ready to announce big changes to the software documentation! After gathering feedback from both IDM researchers and collaborators, we decided to adopt a new content authoring system. This new system, Sphinx, enables many documentation improvements. Most notably, we separated the documentation into multiple disease-specific documentation sets. Each set includes only information and parameters relevant to that disease, making it easier to find the content you need.

Previously, only writers could contribute directly to the docs using proprietary software. Even the process for getting review from researchers or developers was clunky. However, Sphinx is open-source software that produces HTML or PDF output from simple text files that can be read and written in any text editor. The ability to write in any text editor enables greater collaboration with the research and software teams. The documentation source files are now on Github, so anyone at IDM can easily comment on or add to the documentation using the same tools and processes they use for code. Increased collaboration helps content stay up-to-date and complete.

Additionally, Sphinx has extensive reuse and conditional inclusion capabilities for better content management. You can write information in a single file and reuse it across the documentation, so any updates are made in a single place, not many. Information common to all diseases, such as EMOD installation or usage, is reused across all documentation sets. Disease-specific content is conditionally included where appropriate. This reduces the possibility of stale and inconsistent documentation.

Separate documentation sets also required us to reorganize and rewrite a lot of existing content. We removed outdated and redundant content, reorganized for better discoverability, and improved navigation elements. Feedback showed not all researchers want to modify the EMOD source code and built their own executable. We created a separate section for that content and made it easier to understand how to run simulations with an executable built by IDM.

For the 5th Annual Disease Modeling Symposium, we will be releasing three documentation sets from the new system: the Quick Start training tutorials, the generic disease documentation, and the malaria documentation. The HIV and TB documentation is not in the new system yet, but PDFs are available for these diseases.