[GNC-dev] Documentation update problems

Frank H. Ellenberger frank.h.ellenberger at gmail.com
Tue Sep 18 08:53:17 EDT 2018


Hi David Cousens,

In general the wiki needs some modularization to reduce redundancy. That
means, where ever you see similar text, create a new page with the best
parts and replace the pold texts with a link.

OTOH there are different target groups from expirienced coders to less
techie first time contributors to the documentation or translation.

The special art is now to find the right balance.

Am 18.09.18 um 10:19 schrieb 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.

It has been an orphan until yesterday because it has been a draft with
the intension to clarify some confusion about terms around "make". After
David T. confirmed the usability, we should replace similar texts in
other pages by a link, e.g.
https://wiki.gnucash.org/wiki/The_Make_Utility

> 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

In general I do not watch distro specific pages. While other created one
page, Ubunteros are "spamming" the wiki:
BuildGutsy, BuildUbuntu16.04, UbuntuShortcuts, Unity Shortcuts ...

Perhaps you can do some cleanup: Is Gutsy outdated?

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

Shouldn't it be renamed to BuildUbuntu then?

> 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.
ISTR there are some fine parts, which should either go to Building or
get their own page linked from both.

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

The Docs update page was once created by a documenter, who found the
general build page ways to complicate and was for a long time almost
untouched by code developers.

> 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.
> 
> David Cousens

Frank



More information about the gnucash-devel mailing list