Document Update Instructions have been revised

[Chris Good]

> -----Original Message-----
> From: Geert Janssens [mailto:geert.gnucash at kobaltwit.be]
> Sent: Tuesday, 17 January 2017 10:14 PM
> To: Chris Good <chris.good at ozemail.com.au>
> Cc: GnuCash Developers <gnucash-devel at gnucash.org>
> Subject: Re: Document Update Instructions have been revised
> 
> Op dinsdag 17 januari 2017 11:16:39 CET schreef Chris Good:
> > Hi,
> >
> >
> >
> > I've finished updating the wiki Document Update Instructions [1] to
> > include instructions for using 'make' rather than xmllint and xsltproc
> directly.
> >
> > Thank you very much Geert for all the info.
> >
> >
> >
> > [1] http://wiki.gnucash.org/wiki/Documentation_Update_Instructions
> >
> >
> >
> > Regards, Chris Good
> 
> Chris,
> 
> Thanks for improving our documentation on improving our documentation ;)
> 
> Seriously, I appreciate the effort you're spending here.
> 
> I'm proof reading what you have written and below follow some remarks:
> 
> * You are referring to the required use of make, which I like obviously as
I
> suggested that myself. What is not clear in your documentation however is
> how to obtain make and the related tools. On linux this is usually
obtained via
> the package manager. There is usually some kind of package group related
to
> development that installs all the required dependencies in one go. On OS X
I
> don't know how to get it. That's John's expertise although David T may
know
> this by now as well... And on Windows it's probably even more complicated.
> TBH I never tried manually building the gnucash documentation on that
> platform, so I can't give precise instructions. It will likely involve
installing an
> msys environment.
> 
> * Step 5 confuses me:
> "Experienced developers instruct that you should focus first on the
modules
> in either of these two directories (found in the step 1 downloaded files):
> gnucash-docs/help/C or gnucash-docs/guide/C. "
> What do you mean by this ? The "C" directories contain the documentation
in
> English. All other directories contain translations of these in other
languages.
> As I see it there is no need to present this as some kind of mythical
> knowledge only understood by "Experienced developers".
> 
> * The next paragraph confuses me as well. How would opening each file
> reveal errors ? This is not really clear to me.
> 
> * A bit further you suggest to add a pair of comments around your changes
> to help translators. I would propose not to do that as I believe this is
> redundant information. This is what a version management system is used
> for.
> One can use the git history to see what has changed since the last time
one
> has worked on the translation. There are graphical tools like gitk or the
github
> website that help you visualize these changes.
> 
> * "If you are adding or deleting an xml file, for example adding a new
chapter
> or appendix, you also need to update files
[guide|help]/[language]/gnucash-
> {guide|help}.xml and [guide|help]/[language]/Makefile.am. There is no
> need to update Makefile.in as this is generated by running autogen.sh."
> Perhaps here it's best to more explicitly state autogen.sh and
../configure.sh
> should be re-run.
> 
> * There is a section on testing the documentation locally on linux. I have
> slightly modified it, because parts of it were outdated. And I'm
considering
> whether we shouldn't simplify it even more. For now I have stated you can
> run this test with any version of gnucash higher than 2.6.0, with the
> restriction that yelp is installed and working. The text is not too clear
about
> that second part, but that is what the "linux" restriction is actually all
about.
> This does reduce the cases where a full build of a development version of
> gnucash is necessary IMO. It believe this is only necessary when you want
to
> test context help for features that are only in a more recent version than
you
> currently have. But this begs the question whether we really need gnucash
> at all in the other cases. Only yelp suffices as explained at the end of
step
> 11.3. Perhaps we should make that the preferred testing method and only
> propose linux tests in case new context help should be tested. What do you
> think ?
> 
> * Lastly you describe how to format a patch. While this is certainly one
of the
> accepted methods, it may be interesting to document how to make a pull
> request as well.
> 
> That's it. Again, thanks for all the effort you spent on this so far!
> 
> Regards,
> 
> Geert

Hi Geert,

Thanks for reviewing my work and adding extra suggestions. I really enjoy
learning more from your insights. I like to know, at least generally, 'why',
as well as 'how'.
I totally agree your suggestions would be helpful to new documenters. I'm a
little concerned that the bulk of this page could be a little off-putting.
However, I think it is better to have too much info than not enough.
I would like to point out that your suggestions are mostly changes to things
other people wrote. :-)

Originally, I myself started to try to modify the documentation on Windows
but soon thought it was not possible (or at least too difficult), and
changed to Linux.
People who are not familiar with Linux and virtual machines would probably
like more guidance on this.
I have since found that xmllint.exe & xsltproc.exe are in
c:\strawberry\c\bin so that may help. Maybe an msys (or cygwin?) environment
is not needed. I know practically nothing about msys or cygwin. If anyone
else can add anything about updating the documentation on Windows or Mac,
I'd like to hear it.

Re the various translations:
I only speak 1 language, English (Australian) fluently, and some will argue
about that, so it has never really mattered to me, but...
Is it true that the non-English versions of the documentation are
translations of the English documentation?
If so, is this 'policy' or just how it has worked out?
I could imaging that different translations could have totally unique
sections to cater for localisations.

I agree it should be made clearer that it is only necessary to build and
install a development version of GnuCash (programs) if one needs to test
context help for features that are only in a more recent version than
already installed. That section has always been confusing to me.

'Step 2 Git Clone' links to info about using pull requests instead of
patches.
I'll add similar references to the start of ' Step 15 Prepare your Patch'.

Regards, Chris Good
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4817 bytes
Desc: not available
URL: <http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20170118/3f88d020/attachment.p7s>