Re: [Health-dev] Working on the documentation

[Luis Falcon]

Dear Gerald

On Thu, 3 Aug 2023 15:36:52 +0200
Gerald Wiese <wiese@gnuhealth.org> wrote:

> Hi there,
> 
> we didn't get feedback on this apart from Luis mail and Armand
> proposed to work on finances + one case study (which I would highly
> appreciate).
> 
> I'm putting some proposals here. We want to start working on sections
> in detail by Tuesday thus more feedback until then would be great!
> 
> 
> Preface / Resources and Support
> 
> This is not HMIS specific. Could be put on a higher level.

It is important that people read the philosophy and goal of the
project, regardless of the component they will be focusing.

So yes, we need to have the introduction at a higher level. 

I started the GH Wikibook in Nov. 2011 . At that point the book 
was mainly about the HIS ;)

What we can do is to have a link to the preface / Introduction in the
different components.

https://www.gnuhealth.org/docs/

> 
> 
> GNU Health HMIS functionality:
> 
> Rename to Overview, add graphics and explanation + distinction of
> HMIS, HIS, LIS, LIMS etc. with more details. Ensure the acronyms are
> used consistently with the rest of the documentation after defining
> them more precisely.
> 
> 
> Health Information System
> 
> Remove the chapter or put content into it, it’s empty.
> 

This is the section of reporting and analytics. In this section we need
to document the information from the GH HIS and the Federation.

> 
> Federation & Thalamus:
> 
> Functionality and installation of Thalamus should only be explained
> in the Thalamus documentation part. For HMIS it’s enough to link that
> and explain how to use HMIS to connect to it. Besides we should add 
> self-critical notes about the limitations of its current state. If we 
> keep it as a separate chapter I propose to move it after “Modules in 
> Detail” because then you would first explain what is inside HMIS and 
> then move to extensions. Could still appear as link in “Modules in 
> Detail” as there is the health_federation module.
> 
> 

We should merge the information from "Modules in detail" in the
functional areas of the HMIS. 
The rationale is that many packages interact with each other..so
Pediatrics, Surgery, Gyneco, Genetics and specify on each block the
packages that are required as a note.

We need to have a functionality-oriented documentation.


> FHIR REST:
> 
> Let’s just put something like “Work In Progress” or delete it and 
> archive+remove the documentation and actually even the PyPI package. 
> It’s far away from fulfilling the standards and dependency issues 
> causing it to not even be installable alongside HMIS have not been 
> resolved for over two years.
> 

I don't agree at all on this. Both Chris and myself have put quite a
bit of work, time and effort here. If a new Werkzeug or other library
breaks our current code, it's not our fault. We just need time to
update it. That is totally different from being "far away from
fulfilling the standards".

> 
> Installation:
> 
> I can imagine to work on the installation part, however it might make 
> sense to discuss implicit decisions before.
> 
> I suggest to divide it into three areas:
> 
> - Traditional vanilla installation

I will take care of this section. I feel comfortable with this generic
model.

Of course, I always welcome other complementary / alternative
installation methods, as long as they are sustainable in time and there
is a dedicated maintainer.

> 
> - Link other solutions like Ansible, openSUSE zypper or container
> based
> 

Perfect. We will need to include the maintainer information
alongside.


> - Short description how to take PyPI package and deal with database,
> web server, etc. individually for experienced users / administrators, 
> similar to this README:
> 
> https://pypi.org/project/gnuhealth-all-modules/
> 
> 
> Demo and test environments
> 
> Put installation methods to installation chapter, only keep
> description of the demo database and demo server. Change chapters
> name to “Demo Server and Database”
> 
> 
> Plugins
> 
> Rename to e.g. “Client Plugins” or move inside clients chapter.
> 
> 
> Ansible:
> 
> In addition to Luis separation of HMIS, Thalamus & MyGNUHealth I
> would add a separate Ansible documentation as we already have it in
> the mercurial docs repository (copied from my GitLab one).
> 
Good.

Enjoy the weekend
Luis