[GNC-dev] Documentation update problems

[David T.]

Frank, Geert,

I am finally following up on this thread, and I’d like to note that the information that Frank says “got lost,” and which Geert has re-entered on this page were actually moved to a different page (https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment <https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment>) and the reference to this information was moved up to Section 2. Setting Up Your System.

Here we have an example of how duplicative information ends up in our ecosystem!

For the future, we should change the Documentation Update Instructions in this section to point instead to the separate page set up for it. However, there needs to be a clear instruction here as to why a user might need to re-prepare their build environment. I, for one, have no idea why my build environment was broken. I had already followed those directions previously (as evidenced by the existence of the build folder structure on my system), so what broke them? I imagine something along the lines of:

“If you have not built the documentation before, or if you {have changed some miniscule aspect of your system | are incompetent like David T.}, it is usually necessary to reconfigure your build environment as outlined in Initializing Documentation Build Environment.”

Cheers,
David

> On Aug 17, 2018, at 3:25 PM, Frank H. Ellenberger <frank.h.ellenberger at gmail.com> wrote:
> 
> Am 17.08.2018 um 09:18 schrieb Geert Janssens:
>> Op vrijdag 17 augustus 2018 08:41:05 CEST schreef David T. via gnucash-devel:
> :
> 
>>> I’m not sure why there’s a “missing” in the initial command, and I don’t
>>> know where config.guess is supposed to be—and I won’t even try to guess.
>>> 
>>> I would love to have some guidance.
>>> 
>> 
>> I went to look at the wiki page and unfortunately it's incomplete. You get 
>> this error because a few essential commands have been omitted.
>> 
>> I have added a section that should fill the gap. Can you proofread this:
>> https://wiki.gnucash.org/wiki/
>> Documentation_Update_Instructions#Prepare_The_Build_Directory
>> And report back any issues you experience ?
>> 
>> It's written these steps are usually done early in in the set up process, but 
>> you can still run them right now and then retry the validation.
>> 
>> Geert
> 
> Yeah, the missing section got lost in
> https://wiki.gnucash.org/wiki/index.php?title=Documentation_Update_Instructions&type=revision&diff=13215&oldid=12785
> 
> OTOH it was a major improvement of the readability.
> 
> Regards
> Frank
>