Re: [Health-dev] [Health] Working on the documentation

[Yusif Suleiman]

Hi, 
I am very happy with this development, this will really help so many people expecially in developing countries where such systems are few. 
I introduced gnuhealth to many people and small settings, but many failed to fully install and configure the system to their expectations, and because they start to work with it on the recommendation not to have much Interest, the abandoned the project once they encounter any difficulties. 

I believed this is a step for making gnuhealth go higher. 
Greetings. 

Sent from my Huawei Mobile

-------- Original Message --------
Subject: Re: [Health-dev] [Health] Working on the documentation
From: Gerald Wiese
To: Luis Falcon ,health-dev@gnu.org
CC:

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.

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.

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.

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.

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

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

- 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).

Best

Gerald

On 20.07.23 23:19, Luis Falcon wrote:

Hi, Gerald!

On Thu, 20 Jul 2023 16:06:31 +0200
Gerald Wiese <wiese@gnuhealth.org> wrote:

Hey,

we are working on the documentation and aim to have it renewed before 
the conference end of September. One student from Hannover already 
transformed the Wikibooks state into Sphinx Read The Docs Theme and
we can take this as base.

You guys are amazing!
 

I just pushed it but it’s not yet present on any web server.

I just pulled the latest changeset from our mercurial repo in Savannah.

The current HMIS development doc is on the following location:

https://docs.gnuhealth.org/hmis/

We are asking all of you to gather feedback and ideas how to improve
the documentation.

Our first block of questions targets a higher level and we ask for 
responses until end of July.

Second block of questions can be answered afterwards continuously but 
still the sooner the better:


Are there chapters missing?

Do we have chapters that are not needed?

Should we change the structure regarding chapters and subchapters?

Other suggestions for changes on a higher level?


Do we have content missing?

Is every module documented in a way that it’s really complete and 
understandable?

Does it actually work to follow old instructions?

We should update all versions, screenshots, package names, typos, etc.

If functionalities are not really working, we should make it
transparent (e.g. FHIR REST, Thalamus)

Do we have links in place for differing installation strategies and 
other documentations like Thalamus, MyGNUHealth, Ansible, openSUSE?


Beginning of August we will probably start a pad to assign tasks / 
chapters to responsible people.

This is great! We'll be working on the mercurial repo for the
documentation, and updating it directly. I am positive this new
approach will improve the documentation for each component of the GH
ecosystem.

I propose the following layout:

/ root, landing page for docs.gnuhealth.org .. will have the links to
the main areas
/hmis : Hospital management (currently working)
/thalamus: The Federation message server
/mygnuhealth: The Personal Health Record

Let me know your thoughts and congratulations to you and your team,
Gerald!

PS: I' replying  to health-dev@gnu.org to avoid crossposting with
health general. I am positive the general community will be happy to
read it and contribute. We can send them later on an
announcement.

Bests
Luis

Best

Gerald