[GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op zaterdag 8 september 2018 16:57:52 CEST schreef David T. via gnucash-devel:
> Hello,
> 
> As I have noted in another thread recently, I am finding the process of
> updating the various documentation pieces extremely challenging—due in
> large part to the fragmented nature of this documentation. Different
> contributors have placed information on similar topics in any of a number
> of official locations in the GnuCash documentation realm, making the update
> process a circular nightmare.
> 
> This leads to variation in content, approach, and likelihood that a user is
> going to locate the full information on a given subject.
> 
> Rather than tackle each editorial task as if somehow this time it will be
> different, I would like to ask whether there would be support for a
> complete rewrite of the documentation. My idea would be to somehow merge
> all the content from the Guide and the Help into one huge file, and then
> establish a single Grand Unifying Manual that would provide users with a
> single source for help. Contextual help would be stripped back to only
> naming on screen functions, with references back to the GUM in all cases.
> The wiki would remain primarily for specific use cases and temporary
> issues. The FAQ would also point to the docs in most cases. Optionally, I
> would strip out the “Tutorial” aspect of the Tutorial and Concept Guide, as
> I think a solid Manual would obviate the need for this aspect (that, and
> the fact that most of the Tutorail sections are written in a “Hi, how are
> ya” folksie tone that I find inappropriate in formal documentation).
> 
The primary reasons I see for merging the documents are
- easier for the user - there's only one entry point instead of two
- easier for cross linking. In theory you can link across documents but that 
will only work in well-defined conditions. Links in pdf for example won't link 
to another pdf document.

So yes, I see value in merging the documents into one.

Here's my feedback on your proposal:
* Your remark about the "Hi, how are ya" folksie tone brings up an interesting 
question: how do you envision the manual being written ? Is it just the tone 
that's bothering you ? Or the whole idea of use-case driven documentation ? I 
think this is an important point to clear out.

* Thinking a bit more on the duplication issue, I think we should distinguish 
between duplication in the documentation sources and duplication in the end-
user result. Duplication in the sources are always a waste of time and a 
maintenance nightmare. These should clearly be avoided. However in use-case 
driven documentation duplication can be ok. Use case driven documentation 
consists of recipes. Several steps in such recipes are shared across many 
recipes. They can be written once and then reused several times. Can docbook 
or any of the other suggested formats handle such "snippets" ?

* re-reading the proposal it looks like you still suggest to keep two 
documents: one interface help, the fully stripped down document only listing 
all buttons/menus and one with all formal documentation. That of course means 
the linking challenge remains.

* other than that I follow your scope assignments: manual for full 
documentation, wiki for specific (primarily temporary) use-cases, the FAQ 
primarily a list of pointers to the proper documentation.

* and as John suggested: it's best to rally a team for this huge effort.

I'll comment separately on the translation challenge.

Geert