[GNC-dev] Documentation update problems

[Geert Janssens]

Op dinsdag 18 september 2018 10:19:02 CEST schreef David Cousens:
> John, David, Frank
> 
> I wonder at the value of the Build Tools page as a separate orphan entity
> given the more detailed instructions given in the Building Gnucash page.
> There is a fairly good example of dupllcation with it and the following for
> the Gnucash progarm build.
> 
> https://wiki.gnucash.org/wiki/Building
> 
> and the breakout from it for recent Ubuntu versions
> 
> https://wiki.gnucash.org/wiki/BuildUbuntu16.04
> 
> The main building page is a massive tome. I did start breaking out some
> parts of it into smaller logical chunks when I updated the BuildUbuntu16.04
> ( which covers 16.04, 18.04 and Linux MInt 18 and 19 in effect.). The Build
> Tools page may be a logical breakout from there with some of the detail in
> the first page cut into it. There is also a short summary recipe for
> building the Docs at the end of the BuildUbuntu16.04 page which lacks detail
> but does work on Ubuntu and most linux distros. It has no details about the
> dependencies in it though.
> 
> Would a page on building the docs be better as a breakout from the main
> building Gnucash page perhaps with a shared section on the build tools
> referenced from both. For build instructions I ususaly find the recipe the
> most useful bit with explantions of the specific tools as breakouts. If you
> need the information and background you can follow the links. If you only do
> a build occasionally you follow the recipe.  I.e only read the manual when
> you have to.
> 
I wrote my previous mail before looking at the wiki pages you mentioned and I 
agree the current structuring is not guiding the reader to a successful build 
in the most efficient way.

The page could be restructured to be more recipe like with links to pages/
sections with more details.

The general structure of the general instructions is good, but I would not 
differentiate between general and distro specific variants. Building on 
Windows and OS X do merit a separate mention as their build instructions are 
very different. For linux distros as written before the only difference is how 
to get the necessary dependencies set up. It would make sense to add a section 
for this right before getting the gnucash sources.

And as I suggested, the info should be very short on the main building page, 
with a link to a more detailed page specifically about setting up dependencies 
per distro or distro group.

The configuring gnucash section could be reduced to indicating what to do for 
gnucash 2.6.x and what to do for gnucash 3.x by default. More details on 
configuration options could go to a more detailed page on configuring gnucash.

In my opinion the mention of the compiler is not relevant here. If it should 
be mentioned it should be in the section or details on setting up 
dependencies.

All the sections under OS/Distro specific information (other than the two 
links to OS X and Windows should IMO be removed from this page. The details of 
setting up dependencies can be grouped on the new page for this, the build 
instructions themselves are identical for all distros. Oh and anything that's 
valid only for obsolete distros should be removed completely. The oldest 
supported Ubuntu distro is 14.04 LTS, for Fedora that's 27. I would not 
mention distro releases unless it's necessary to differentiate. In that case I 
would write the default instructions for the current distro (omitting distro 
release info) and exceptional instructions for the older distro(s) (adding for 
which distro this matters). That will make it easier to maintain the 
documentation in the future:
- if nothing changes when a new disto release comes out, documentation doesn't 
need to be updated
- if a distro becomes obsolete, it's easy to find and remove all info that's 
no longer relevant.

Geert