GenevaERS documentation discussions

[emorrow38]

This issue will cover the discussions in the GenevaERS project about documentation.

[emorrow38]

MEETING held Thursday October 15 (USA) and Friday October 16 (Australia).

Ian Cunningham reported that Docker makes install of Postgres a lot easier - just use a docker container for Postgres.

Randall Ness talked about changes to overall Help documentation for GenevaERS. In the past we had three types of help:

1. Embedded help inside the workbench for SAFR (the name for GenevaERS inside IBM).
2. An internal IBM website for SAFR (see Info Center 4.15) that a few select customers could view.
3. PDF files which are included in the SAFR Website.

Randall said the new Help documentation for GenevaERS would be:

1. A public website for GenevaERS general documentation (a separate site from genevaers.org).
2. An IBM internal website(s) for the version of GenevaERS that involves paid support from IBM. IBM customers purchasing that support can access the IBM internal websites.

Randall noted that previously, the workbench had context sensitive help - if a user pressed F`1 on a screen X then help popped up that was relevant to screen X. However, this feature is no longer supported by software we are using to generate the workbench embedded help, and would be too costly to do manually, so the embedded help would not longer be available. Instead, when a user pressed F1 then they would be directed to the GenevaERS General documentation website.

The meeting confirmed that the future direction for help documentation for GenevaERS is markdown files (instead of the older DITA files used by IBM).

Randall also noted that to speed up help documentation for GenevaERS there would not be screen images in the help itself, as this a large task to maintain. Instead the help documentation would concentrate on the text content needed by users. Eugene Morrow noted that there would still be images in the help documentation, for example to show screen icons.

Kip Twitchell suggested that the converted DITA help would be marked "Under construction" so that users would know that the help is being improved and is not yet final.

Kip recommended we create an internal folder inside IBM to collect raw materials that can be turned into help documentation. The raw materials would remain inside IBM as they could have commercial confidential material that must be removed before becoming part of an open source system.

[emorrow38]

Meeting held Thursday October 21 (USA) and Friday October 22 (Australia)

Randall Ness noted that the meeting agreed that accuracy was more important the completeness for the help documentation. Users needed to be able to trust what they read, and would understand if areas of help were still under construction.

Meeting agreed to create this issue under repo Github Genevaers doc. This issue will track the meetings about Genevaers documentation and Eugene Morrow would make these entries.

Meeting agreed that specific documentation issues (for example the high level structure) would each be in a separate issue so that participants can comment and progress that specific issue. Randall Ness is converting his Word document that has an outline of the high level structure into a markdown document using Visual Studio Code. This will allow participants to expand and collapse areas of the structure at will. Meeting agreed this is the way to progress the help documentation in a top-down manner.

Meeting agreed that the "V4" in Randall's current outline can be removed. Meeting noted that there will be at least two version numbers of GenevaERS at all times - one version is free and open source, and the other version is the one used when customers have paid for IBM support. The version of the product will distinguish which website users access for the help documentation.

Randall Ness noted how help documentation will need to be assembled from the "free" GenevaERS plus the "supported" GenevaERS, and possibly with extras parts added by customers themselves. Ian Cunningham and Eugene Morrow both believe this can be done by reusing markdown files that are common to all of these.

Randall Ness will decide if he prefers "User Guide" or "User Manual". Ian Cunningham suggested that "User Manual" can be the bit documentation component that contains smaller "guides" for specific tasks.

Gillian Hannington recommended a "Sample JCL" folder in the Performance Engine repo so that users can access some miscellaneous JCL that will be needed in various situations of using GenevaERS.

Eugene Morrow said that the best way to documentr the many ways that GenevaERS can be used is to have End-to-End examples. One example might be using GenevaERS to read from DB2 databases, and the End-to-End Example for this would cover the Workbench config and the JCL required to run the Performance Engine, along with the necessary planning and analysis for this technique. The GenevaERS documentation will need many such End-to-End Examples.

Ian Cunningham noted that the Workbench involves two major components - the metadata repository and the workbench itself. It is possible to setup the metadata repository once, but the workbench itself may be upgraded many times while still working with the same metadata repository.

[emorrow38]

I have posted a file called "GenevaERS_structure_of_help_topics.md".

View this file in Visual Studio Code.

You will see a list of names of proposed help topics for the main GenevaERS documentation website. You can expand or collapse the list of topics to see where one topic has many sub-topics. When a topic expands that means that that topic will also be a folder that contains those sub-topics (when they are all completed). For now this is a list of topic names only showing the folders and overall structure.

The idea is that we all look at the list of help topic names and see if there are items that are missing (lots). We want to list all the topics we want to create before we plunge into writing help topics.