How to document OpenHospital

Background

A very known problem of documentation is first all to produced it and the second it to keep it updated. Notoriusly devs don't like to document their feature and editors are not enough informed about changes happend in the code. For this reason there is often a problem of lack of documentation and/or outdated. Moreover, the whole documentation should alwasy be versioned across releases.

The ideal goal would be to find a way to achieve a strong link with the code, in a way that the developer developing a feature can easily "mark" where the doc is suscetible of change, so other people (or the dev him/herself) can subsequently revise and update them. Moreover, every change should be tracked and tagged with the correspondent code release version. Finally, each version (meant as collection of release tags) should be downloadable in a single PDF document.

Some tools that may be evaluated are:

• Confluence itself: to see if the dev or the merger can mark any page via smart commits
• Asciidoctor
• LaTeX
• MkDocs
• Read the Docs

This decision involves:

OP-7 - Getting issue details... STATUS

OP-8 - Getting issue details... STATUS

OP-9 - Getting issue details... STATUS

Options considered

Action items

Every solution should be studied individually, keeping in mind the overall process of development and also that people documenting can change over time like developers

• Alessandro Domanico Evaluate Confluence
• Alessandro Fanna Evaluate Asciidoctor
• Alessandro Fanna Evaluate LaTeX
• Evaluate MkDocs
• Evaluate Read the Docs

Outcome