Re: [GNC-dev] Long Term Documentation Directions

[Mechtilde]

Hello,
sorry I send the E-Mail not to the list.

Am 12.09.18 um 12:59 schrieb David Cousens:
> Mechtilde,
> 
> I wasn't suggesting we use google translate at all where there is a human 
> translator available and willing, but in some
> languages it may be difficult to get a translator, even though there may be 
> users. I admit German would be problematical
> because of the compound word structure and some of the differences in 
> sentence structure from English so google
> translate might not do too good a job there. There are also  usually many 
> differences between formal language and the
> more colloquial usage. I wasn't really thinking of something complex like the 
> Tutorial and Concepts guide but more the
> single line descrition of buttons etc in the interface.

It is more complicate to translate a "single line description" or a
button in an interface than a log description of a function.

The different between an American accounting and a German accounting is
more than a translation of words or sentence. You have to look how is
the naming in the different culture of doing accounting.

E.g "bill" and "invoices" is named "Rechnung" and visa verse "Expense"
is named "Audgabe" or "Aufwand" which are two different things in German
accounting.

This is important for Business accounting.

Kind regards
Mechtilde

> David
> 
>  Tue, 2018-09-11 at 19:45 +0200, Mechtilde wrote:
>> Hello David,
>>
>>
>> Am 10.09.18 um 15:26 schrieb David Cousens:
>>> Geert,
>>>
>>> Is there not perhaps a way to leverage Google translate as a first pass to
>>> translate text. The result may not be colloquial and produce some
>>> interesting results. I have used it for Russian to English translations and
>>> it doesn't do too bad a job.
>>> https://translate.google.com/toolkit/docupload?hl=en
>>
>> Please, NO. NO automatic translation of something like Tutorial and
>> Concepts of GnuCash.
>> You need human fuzzy logic to understand the American Accounting Meaning
>> and the analog Meaning in the native language.
>>
>> For my German translation experince sometimes you have two word in
>> English and one in German or vice versa. I think that there are simalar
>> problems in the other languages.
>>
>>>
>>> David
>>>
>>
>> Kind regards

-- 
Mechtilde Stehmann
## Apache OpenOffice
## Freie Office Suite für Linux, MacOSX, Windows
## Debian Developer
## Loook, calender-exchange-provider, libreoffice-canzeley-client
## PGP encryption welcome
## F0E3 7F3D C87A 4998 2899  39E7 F287 7BBA 141A AD7F



signature.asc
Description: OpenPGP digital signature
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

John, 

Point taken. I rarely use the yelp viewer from inside Gnucash at all and
mainly use the online HTML documentation.  It could be to separate context
sensitive help into it's own structureis one way to go. I would have thought
for the more tutorial aspects currently in the guide it would also be useful
to link to widget specific information  e.g. a reference to a specific
button as a link to the button description and not have to include what the
button does. .

I think the current documentation processing for docbook xml takes care of
that by editing out features that are not supported in a particular format
using the xsl files or converting to the appropriate format. PDF and HTML
both have the capacity to construct internal and external links.
https://helpx.adobe.com/acrobat/kb/link-html-pdf-page-acrobat.html suggests
it is possible to link to specific points in a pdf.

I think Geert's point about  someone imposing quality control and some sort
of editorial policy is quite valid.

David Cousens



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[John Ralls]

> On Sep 11, 2018, at 5:12 PM, David Cousens  wrote:
> 
> Hi John,
> 
> I do understand that alternatives to docbook are being considered. 
> 
> I keep referring to it primarily because it is the current format, rather
> than necessarily the best or even what may be used in future. Perhaps with
> an assumption that whatever format is decided on, it will at least have the
> same conversion capabilities and the ability to construct an automated build
> workflow as are present in the current documentation tool chain. 
> 
> Also as a way of arguing for not embedding context sensitive help in hard
> code if it is avoidable. I do take the point though that such information
> does only change slowly if at all so I think a separate file perhaps with a
> more restricted editing access could be a way to handle that. 
> 
> The availability of some good open source free wsiwyg editors for markdown
> would certainly help  documenters with a less technical background and
> pandoc seems to be capable of building into a toolchain for converion for
> example. I haven't found out yet whether it uses some form of xls to control
> the conversion which is customizable.

David,

That misses the point a bit, which is that regardless of what format we keep 
the sources in the documents that users read will mostly be some form of HTML 
or PDF and we're limited to the feature set that those markup languages 
provide. For the current discussion that particularly applies with respect to 
cross-document links.

Regards,
John Ralls

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

Hi John,

I do understand that alternatives to docbook are being considered. 

I keep referring to it primarily because it is the current format, rather
than necessarily the best or even what may be used in future. Perhaps with
an assumption that whatever format is decided on, it will at least have the
same conversion capabilities and the ability to construct an automated build
workflow as are present in the current documentation tool chain. 

Also as a way of arguing for not embedding context sensitive help in hard
code if it is avoidable. I do take the point though that such information
does only change slowly if at all so I think a separate file perhaps with a
more restricted editing access could be a way to handle that. 
 
The availability of some good open source free wsiwyg editors for markdown
would certainly help  documenters with a less technical background and
pandoc seems to be capable of building into a toolchain for converion for
example. I haven't found out yet whether it uses some form of xls to control
the conversion which is customizable.

David Cousens



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op maandag 10 september 2018 17:26:44 CEST schreef David T. via gnucash-devel:
> The idea of use-case recipes sounds rather like the “walkthrough" described
> in the pronovix article, which they clearly see as a specific, separate,
> experience. Such resources have their place, but not in the Concept Guide.
> Walkthroughs could use DocBook ENTITY mechanisms to cobble together
> snippets of steps into a single sequence, but that makes my head hurt, so I
> won’t be the one taking that project on.
> 
You don't have to of course. I'm happy with your current initiative as well.

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op dinsdag 11 september 2018 15:13:51 CEST schreef David T.:
> Hello,
> 
> > On Sep 11, 2018, at 4:45 AM, Geert Janssens 
> > wrote:> 
> > Op dinsdag 11 september 2018 09:15:43 CEST schreef David Cousens:
> >> David,
> >> 
> >> Just some comments on a couple of other points:
> >> 
> >> Embedding even the context help in the program code is not a really good
> >> idea. It means that text cannot be edited /altered easily separately from
> >> the program and without rebuilding the program.
> > 
> > You raise a good point here. Aside from the building restriction (which we
> > now also have for source message translations), it would probably limit
> > the potential help writing contributors to only those people capable of
> > parsing the source code. In practice there would be few outside of the
> > developers themselves. And those are known not to be the best
> > documentation writers :(
> Geert, you note that the developers are not proficient documentors, and I
> agree with you. You also say that you’d prefer the broader documentation
> team (such as it is) to be able to edit this context help.
> 
> One major reason for my suggesting that context help be embedded in code is
> a direct response to the current situation, where well-intentioned
> documentation contributors have placed duplicative information in
> *different places.* Deciding when a “small piece of prose” (as you put it,
> Geert) crosses that magical threshold from context help into concept guide
> is precisely what has led this documentation into the mess it’s in.
> Although it’s perhaps heresy, I think that limiting the ability of the
> Documentation Team to make contributions to the Help might not be a bad
> idea. Push everyone to the Guide, instead.

Well, that's one way of looking at it. I think the main reason why we have 
duplication is because there hasn't been anyone who took responsibility for 
the documentation in years and perhaps there never was. Someone to set clear 
directions and guard them. Someone that would review contributions and direct 
contributors in the right direction.

John and I do this for the code, but there's no one doing that for 
documentation really.

As such I'm very pleased with your initiative to clarify the boundaries of 
documentation. And frankly I don't really care that much what those are in 
detail. As long as it works as a clear framework for anyone interested in 
contributing. And that it will be backed by a couple of people to guide new 
contributors. I understand you and David Cousens are willing to rework the 
existing documentation. Great! Are you also willing to review work done by 
others and tell them to relocate if their initial suggestion isn't right ?

> 
> I envision that the context help would consist of short _functional_
> descriptions of one or two sentences. I believe that the rate of change in
> the functions of the UI elements is exceedingly small. In my decade-plus
> time using GnuCash, I haven’t seen many changes to the buttons or screens.
> Accounting hasn’t suddenly come up with an entirely new set of functions.
> This leads me to the conclusion that functional descriptions of those
> buttons and screens won’t need to change either. If the functional aspects
> of the interface don’t change, then the context help doesn’t need to
> change, either. If the content isn’t changing, then the authorial skill of
> developers is beside the point.
> 
> In other words, unless there is a change in function, there is no need to
> change the functional description. It seems to me that putting text that
> doesn’t change into code is essentially a one-time process. Not necessarily
> easy, but once completed, not particularly obtrusive. Putting the
> functional description into code has the added benefit, perhaps, of
> alerting developers to the fact that if they change a feature, the
> description (right there in the code) needs an update as well.

As for the context help in particular, this discussion is too abstract for me. 
I have a feeling you and I are thinking of different things when we write 
about context help or how to handle it.

In addition I worry we're trying to change too much at once. You started with 
the goal of deduplicating content and for that you propose to move most 
content from help to guide. I'm all with you. I propose to do that first and 
*then* see what remains of the help document and decide what to do with it.

> > So I vote for keeping all help consisting of more than a single sentence
> > in a separate document. So a short tooltip or a hint in an empty text
> > entry go into the code (also for practical reasons), but a small piece of
> > prose explaining how a certain dialog window works should go in a
> > document that is more easily edited by documentation writers.
> > 
> > What we may be able to do is write some scripts that would automatically
> > extract a list of all user interface elements from the source code and
> > compose a skeleton document from this. 

Re: [GNC-dev] Long Term Documentation Directions

[Adrien Monteleone]

Yes, sorry. I misspoke on that last point.

Regards,
Adrien

> On Sep 11, 2018, at 1:10 PM, David T.  wrote:
> 
> Adrien,
> 
> I’ll note here that you seem to have the documentation model backwards, 
> insofar as you suggest that interface changes wouldn’t affect the Guide. I 
> believe that such changes would not affect the Help, whereas changes in the 
> UI and the form and location of a given widget would definitely be reflected 
> in the Guide, since that is where the descriptive explanation of GnuCash and 
> its functions will reside. The Help would only consist of context help 
> containing a sentence or two about that widget.
> 
> David
> 


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David T. via gnucash-devel]

Adrien,

> On Sep 11, 2018, at 1:09 PM, Adrien Monteleone 
>  wrote:
> 
> 
> 
>> On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel 
>>  wrote:
>> 
>> Hello,
>> 
>> 
>> I envision that the context help would consist of short _functional_ 
>> descriptions of one or two sentences. I believe that the rate of change in 
>> the functions of the UI elements is exceedingly small. In my decade-plus 
>> time using GnuCash, I haven’t seen many changes to the buttons or screens. 
>> Accounting hasn’t suddenly come up with an entirely new set of functions. 
>> This leads me to the conclusion that functional descriptions of those 
>> buttons and screens won’t need to change either. If the functional aspects 
>> of the interface don’t change, then the context help doesn’t need to change, 
>> either. If the content isn’t changing, then the authorial skill of 
>> developers is beside the point. 
>> 
>> In other words, unless there is a change in function, there is no need to 
>> change the functional description. It seems to me that putting text that 
>> doesn’t change into code is essentially a one-time process. Not necessarily 
>> easy, but once completed, not particularly obtrusive. Putting the functional 
>> description into code has the added benefit, perhaps, of alerting developers 
>> to the fact that if they change a feature, the description (right there in 
>> the code) needs an update as well.
> 
> While the principles might not change, or even the name/label of certain 
> buttons, the UI layout (where those buttons are, the fact that they are 
> buttons instead of menu entries, etc.) will very likely change as the Gnome 
> HIG is more faithfully implemented. But those code changes shouldn’t affect 
> anything generally in the Guide, and should auto update the context help if 
> it is drawn from the code itself. If not, then consider that attempts to 
> corral GnuCash within the confines of the Gnome HIG, will produce such 
> changes you’re thinking won’t happen.
> 

We are in general agreement here. My point was that any context help text, 
being based on the *actual function* of a given widget (and regardless of the 
form or broader context of that widget) is unlikely to change. Geert was 
concerned that embedding help text in code would shield that text from the 
editorial expertise of members of the Documentation Team. I was trying to point 
out that these texts, once written, are unlikely to need rewriting unless the 
actual functions change. 

I’ll note here that you seem to have the documentation model backwards, insofar 
as you suggest that interface changes wouldn’t affect the Guide. I believe that 
such changes would not affect the Help, whereas changes in the UI and the form 
and location of a given widget would definitely be reflected in the Guide, 
since that is where the descriptive explanation of GnuCash and its functions 
will reside. The Help would only consist of context help containing a sentence 
or two about that widget.

David


> Regards,
> Adrien
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[John Ralls]

I don't know about allowing room for it, but it's pretty far in the future 
because we still have too many Gnome dependencies in the core and too many MVC 
violations to be able to implement a different toolkit.

Regards,
John Ralls


> On Sep 11, 2018, at 10:23 AM, Adrien Monteleone 
>  wrote:
> 
> Then I misunderstood some earlier discussions about the UI, at least with 
> respect to Linux. What toolkit is envisioned to be used? What layout 
> principles? Or are those questions so far in the future as to not be worth 
> spending time allowing room for?
> 
> Regards,
> Adrien
> 
>> On Sep 11, 2018, at 12:18 PM, John Ralls  wrote:
>> 
>> 
>> 
>>> On Sep 11, 2018, at 10:09 AM, Adrien Monteleone 
>>>  wrote:
>>> 
>>> 
>>> 
 On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel 
  wrote:
 
 Hello,
 
 
 I envision that the context help would consist of short _functional_ 
 descriptions of one or two sentences. I believe that the rate of change in 
 the functions of the UI elements is exceedingly small. In my decade-plus 
 time using GnuCash, I haven’t seen many changes to the buttons or screens. 
 Accounting hasn’t suddenly come up with an entirely new set of functions. 
 This leads me to the conclusion that functional descriptions of those 
 buttons and screens won’t need to change either. If the functional aspects 
 of the interface don’t change, then the context help doesn’t need to 
 change, either. If the content isn’t changing, then the authorial skill of 
 developers is beside the point. 
 
 In other words, unless there is a change in function, there is no need to 
 change the functional description. It seems to me that putting text that 
 doesn’t change into code is essentially a one-time process. Not 
 necessarily easy, but once completed, not particularly obtrusive. Putting 
 the functional description into code has the added benefit, perhaps, of 
 alerting developers to the fact that if they change a feature, the 
 description (right there in the code) needs an update as well.
>>> 
>>> While the principles might not change, or even the name/label of certain 
>>> buttons, the UI layout (where those buttons are, the fact that they are 
>>> buttons instead of menu entries, etc.) will very likely change as the Gnome 
>>> HIG is more faithfully implemented. But those code changes shouldn’t affect 
>>> anything generally in the Guide, and should auto update the context help if 
>>> it is drawn from the code itself. If not, then consider that attempts to 
>>> corral GnuCash within the confines of the Gnome HIG, will produce such 
>>> changes you’re thinking won’t happen.
>> 
>> Why do you think we're going to "more faithfully implement" the Gnome HIG? 
>> One of our long-term goals is to remove our Gnome dependencies. 
>> 
>> Regards,
>> John Ralls
> 
> 
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[John Ralls]

> On Sep 11, 2018, at 8:13 AM, David Cousens  wrote:
> 
> Hi Geert 
> 
> "I know you can define these links in docbook. However my remark earlier in 
> this thread is how will they work in practice ? How can one document on the 
> system know where the other is stored ? I presume this means we should have 
> strict rules about the relative locations of documents. And those should be 
> communicated properly to gnucash-documentation packagers for various 
> distributions"
> 
> The links between different docbook documents can be handled with XML
> catalogues. 
> It looks like you define generic paths for links during the document build
> and use those generic names as the URLs in the code you call to bring them
> up in the program. The generic names are linked by  xsltprocto the actual
> URLs in the catalog.xml  file which resides by default in /etc/xml/catalog
> but can be redirected to something like /usr/share/gnucash/xml/catalog.xml
> with an environment variable  XML_CATALOGUE_FILE during the document build.
> xsltproc appears to construct the links between the files. Not sure how the
> program handles that. I'll keep digging to see what i can come up with.
> 
> Not sure about what happens with the PDF etc  but I think xsltproc uses
> specific  xsl files to process them the same as it does now. 
> 
> (http://sagehill.net/docbookxsl/Catalogs.html#WhyCatalogs)

Well, it's "PDF etc" (where etc. means the various HTML formats including epub, 
mobi, and chm, in which most users read the docs) that's the issue. Only Yelp 
directly reads Docbook-formatted documents, so that's not useful to most of our 
users.

Docbook may well be the eighth wonder of the documentation world but for our 
purposes it's only a way of marking up document sources. We can't use any of 
its feature that don't map to HTML and PDF.

Regards,
John Ralls

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Adrien Monteleone]

Then I misunderstood some earlier discussions about the UI, at least with 
respect to Linux. What toolkit is envisioned to be used? What layout 
principles? Or are those questions so far in the future as to not be worth 
spending time allowing room for?

Regards,
Adrien

> On Sep 11, 2018, at 12:18 PM, John Ralls  wrote:
> 
> 
> 
>> On Sep 11, 2018, at 10:09 AM, Adrien Monteleone 
>>  wrote:
>> 
>> 
>> 
>>> On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel 
>>>  wrote:
>>> 
>>> Hello,
>>> 
>>> 
>>> I envision that the context help would consist of short _functional_ 
>>> descriptions of one or two sentences. I believe that the rate of change in 
>>> the functions of the UI elements is exceedingly small. In my decade-plus 
>>> time using GnuCash, I haven’t seen many changes to the buttons or screens. 
>>> Accounting hasn’t suddenly come up with an entirely new set of functions. 
>>> This leads me to the conclusion that functional descriptions of those 
>>> buttons and screens won’t need to change either. If the functional aspects 
>>> of the interface don’t change, then the context help doesn’t need to 
>>> change, either. If the content isn’t changing, then the authorial skill of 
>>> developers is beside the point. 
>>> 
>>> In other words, unless there is a change in function, there is no need to 
>>> change the functional description. It seems to me that putting text that 
>>> doesn’t change into code is essentially a one-time process. Not necessarily 
>>> easy, but once completed, not particularly obtrusive. Putting the 
>>> functional description into code has the added benefit, perhaps, of 
>>> alerting developers to the fact that if they change a feature, the 
>>> description (right there in the code) needs an update as well.
>> 
>> While the principles might not change, or even the name/label of certain 
>> buttons, the UI layout (where those buttons are, the fact that they are 
>> buttons instead of menu entries, etc.) will very likely change as the Gnome 
>> HIG is more faithfully implemented. But those code changes shouldn’t affect 
>> anything generally in the Guide, and should auto update the context help if 
>> it is drawn from the code itself. If not, then consider that attempts to 
>> corral GnuCash within the confines of the Gnome HIG, will produce such 
>> changes you’re thinking won’t happen.
> 
> Why do you think we're going to "more faithfully implement" the Gnome HIG? 
> One of our long-term goals is to remove our Gnome dependencies. 
> 
> Regards,
> John Ralls


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[John Ralls]

> On Sep 11, 2018, at 10:09 AM, Adrien Monteleone 
>  wrote:
> 
> 
> 
>> On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel 
>>  wrote:
>> 
>> Hello,
>> 
>> 
>> I envision that the context help would consist of short _functional_ 
>> descriptions of one or two sentences. I believe that the rate of change in 
>> the functions of the UI elements is exceedingly small. In my decade-plus 
>> time using GnuCash, I haven’t seen many changes to the buttons or screens. 
>> Accounting hasn’t suddenly come up with an entirely new set of functions. 
>> This leads me to the conclusion that functional descriptions of those 
>> buttons and screens won’t need to change either. If the functional aspects 
>> of the interface don’t change, then the context help doesn’t need to change, 
>> either. If the content isn’t changing, then the authorial skill of 
>> developers is beside the point. 
>> 
>> In other words, unless there is a change in function, there is no need to 
>> change the functional description. It seems to me that putting text that 
>> doesn’t change into code is essentially a one-time process. Not necessarily 
>> easy, but once completed, not particularly obtrusive. Putting the functional 
>> description into code has the added benefit, perhaps, of alerting developers 
>> to the fact that if they change a feature, the description (right there in 
>> the code) needs an update as well.
> 
> While the principles might not change, or even the name/label of certain 
> buttons, the UI layout (where those buttons are, the fact that they are 
> buttons instead of menu entries, etc.) will very likely change as the Gnome 
> HIG is more faithfully implemented. But those code changes shouldn’t affect 
> anything generally in the Guide, and should auto update the context help if 
> it is drawn from the code itself. If not, then consider that attempts to 
> corral GnuCash within the confines of the Gnome HIG, will produce such 
> changes you’re thinking won’t happen.

Why do you think we're going to "more faithfully implement" the Gnome HIG? One 
of our long-term goals is to remove our Gnome dependencies. 

Regards,
John Ralls

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Adrien Monteleone]

> On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel 
>  wrote:
> 
> Hello,
> 
> 
> I envision that the context help would consist of short _functional_ 
> descriptions of one or two sentences. I believe that the rate of change in 
> the functions of the UI elements is exceedingly small. In my decade-plus time 
> using GnuCash, I haven’t seen many changes to the buttons or screens. 
> Accounting hasn’t suddenly come up with an entirely new set of functions. 
> This leads me to the conclusion that functional descriptions of those buttons 
> and screens won’t need to change either. If the functional aspects of the 
> interface don’t change, then the context help doesn’t need to change, either. 
> If the content isn’t changing, then the authorial skill of developers is 
> beside the point. 
> 
> In other words, unless there is a change in function, there is no need to 
> change the functional description. It seems to me that putting text that 
> doesn’t change into code is essentially a one-time process. Not necessarily 
> easy, but once completed, not particularly obtrusive. Putting the functional 
> description into code has the added benefit, perhaps, of alerting developers 
> to the fact that if they change a feature, the description (right there in 
> the code) needs an update as well.

While the principles might not change, or even the name/label of certain 
buttons, the UI layout (where those buttons are, the fact that they are buttons 
instead of menu entries, etc.) will very likely change as the Gnome HIG is more 
faithfully implemented. But those code changes shouldn’t affect anything 
generally in the Guide, and should auto update the context help if it is drawn 
from the code itself. If not, then consider that attempts to corral GnuCash 
within the confines of the Gnome HIG, will produce such changes you’re thinking 
won’t happen.

Regards,
Adrien
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

Hi Geert 

"I know you can define these links in docbook. However my remark earlier in 
this thread is how will they work in practice ? How can one document on the 
system know where the other is stored ? I presume this means we should have 
strict rules about the relative locations of documents. And those should be 
communicated properly to gnucash-documentation packagers for various 
distributions"

The links between different docbook documents can be handled with XML
catalogues. 
It looks like you define generic paths for links during the document build
and use those generic names as the URLs in the code you call to bring them
up in the program. The generic names are linked by  xsltprocto the actual
URLs in the catalog.xml  file which resides by default in /etc/xml/catalog
but can be redirected to something like /usr/share/gnucash/xml/catalog.xml
with an environment variable  XML_CATALOGUE_FILE during the document build.
xsltproc appears to construct the links between the files. Not sure how the
program handles that. I'll keep digging to see what i can come up with.

Not sure about what happens with the PDF etc  but I think xsltproc uses
specific  xsl files to process them the same as it does now. 

(http://sagehill.net/docbookxsl/Catalogs.html#WhyCatalogs)

Cheers

David Cousens



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David T. via gnucash-devel]

Hello,

> On Sep 11, 2018, at 4:45 AM, Geert Janssens  
> wrote:
> 
> Op dinsdag 11 september 2018 09:15:43 CEST schreef David Cousens:
>> David,
>> 
>> Just some comments on a couple of other points:
>> 
>> Embedding even the context help in the program code is not a really good
>> idea. It means that text cannot be edited /altered easily separately from
>> the program and without rebuilding the program. 
> 
> You raise a good point here. Aside from the building restriction (which we 
> now 
> also have for source message translations), it would probably limit the 
> potential help writing contributors to only those people capable of parsing 
> the source code. In practice there would be few outside of the developers 
> themselves. And those are known not to be the best documentation writers :(
> 

Geert, you note that the developers are not proficient documentors, and I agree 
with you. You also say that you’d prefer the broader documentation team (such 
as it is) to be able to edit this context help.

One major reason for my suggesting that context help be embedded in code is a 
direct response to the current situation, where well-intentioned documentation 
contributors have placed duplicative information in *different places.* 
Deciding when a “small piece of prose” (as you put it, Geert) crosses that 
magical threshold from context help into concept guide is precisely what has 
led this documentation into the mess it’s in. Although it’s perhaps heresy, I 
think that limiting the ability of the Documentation Team to make contributions 
to the Help might not be a bad idea. Push everyone to the Guide, instead.

I envision that the context help would consist of short _functional_ 
descriptions of one or two sentences. I believe that the rate of change in the 
functions of the UI elements is exceedingly small. In my decade-plus time using 
GnuCash, I haven’t seen many changes to the buttons or screens. Accounting 
hasn’t suddenly come up with an entirely new set of functions. This leads me to 
the conclusion that functional descriptions of those buttons and screens won’t 
need to change either. If the functional aspects of the interface don’t change, 
then the context help doesn’t need to change, either. If the content isn’t 
changing, then the authorial skill of developers is beside the point. 

In other words, unless there is a change in function, there is no need to 
change the functional description. It seems to me that putting text that 
doesn’t change into code is essentially a one-time process. Not necessarily 
easy, but once completed, not particularly obtrusive. Putting the functional 
description into code has the added benefit, perhaps, of alerting developers to 
the fact that if they change a feature, the description (right there in the 
code) needs an update as well.

> So I vote for keeping all help consisting of more than a single sentence in a 
> separate document. So a short tooltip or a hint in an empty text entry go 
> into 
> the code (also for practical reasons), but a small piece of prose explaining 
> how a certain dialog window works should go in a document that is more easily 
> edited by documentation writers.
> 
> What we may be able to do is write some scripts that would automatically 
> extract a list of all user interface elements from the source code and 
> compose 
> a skeleton document from this. Then with some clever msgmerge like magic 
> merge 
> existing help strings from a previous version of this document. That would at 
> least make sure the list of interface elements can be kept up to date 
> programmatically so no one should scan the sources manually for changes.
> 

Keeping in mind that the Help is meant to be *contextual*—that is, linked 
directly to the screens and widgets a user encounters in GnuCash—perhaps the 
Help document should be more strictly structured to reflect this. Set it up as 
a table, with a column that provides the link to the interface, a column for 
the (brief) help text, and a column to link to the guide. This sort of 
structure exists already in some places of the Help; converting the entire 
document to this format would make clear to future writers and users that the 
Help is primarily meant for access from the application. People looking for 
more explanation would be directed to the Concept Guide. In an absolute sense, 
there is no real need for chapter headings, screen titles, figures, etc., since 
user access to this document would strictly be from the application itself. You 
could, I guess, go the other direction, and create separate files for each 
individual entry. To me, madness lies down that alley.

> 
>> My understanding is that it
>> can be done from a docbook that just has the links to a section which is
>> displayed in response to a help button being pressed or  something like a
>> Shift-F1 key combination while the focus is on the button/checkbox/etc that
>> you want help on. It could be a separate window from the main 

Re: [GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op dinsdag 11 september 2018 09:15:43 CEST schreef David Cousens:
> David,
> 
> Just some comments on a couple of other points:
> 
> Embedding even the context help in the program code is not a really good
> idea. It means that text cannot be edited /altered easily separately from
> the program and without rebuilding the program. 

You raise a good point here. Aside from the building restriction (which we now 
also have for source message translations), it would probably limit the 
potential help writing contributors to only those people capable of parsing 
the source code. In practice there would be few outside of the developers 
themselves. And those are known not to be the best documentation writers :(

So I vote for keeping all help consisting of more than a single sentence in a 
separate document. So a short tooltip or a hint in an empty text entry go into 
the code (also for practical reasons), but a small piece of prose explaining 
how a certain dialog window works should go in a document that is more easily 
edited by documentation writers.

What we may be able to do is write some scripts that would automatically 
extract a list of all user interface elements from the source code and compose 
a skeleton document from this. Then with some clever msgmerge like magic merge 
existing help strings from a previous version of this document. That would at 
least make sure the list of interface elements can be kept up to date 
programmatically so no one should scan the sources manually for changes.


> My understanding is that it
> can be done from a docbook that just has the links to a section which is
> displayed in response to a help button being pressed or  something like a
> Shift-F1 key combination while the focus is on the button/checkbox/etc that
> you want help on. It could be a separate window from the main help system
> which just pops up displays the information and closes when you finish (i.e
> no navigation - want help on something else-click on something else and hit
> shift F10 -  but pulls its text from a HTML file created from a
> docbook/asciidoc or similar source help file. It would not necessarily have
> to have such a file broken up into subfiles.
> 
> The same would also be true of the Concepts guide. It could be modules
> within a single file or a collection of files which can either be displayed
> independently or linked together to form a full document. The existing Help
> manual are organised a bit like that but the separate files for the chapters
> do not have document headers so they can't be displayed independently .
> What I mean by that is you can point a browser at the derived HTML file for
> a chapter and have it display just that chapter without having to load the
> whole Help manual and navigate to the bit you want. In any case breaking it
> into separate source files is not a high priority but it may make some
> sense to have related content in its own module futher down the track. It
> can also be done progressively once the content  has been rearranged.
> 
Indeed. We should primarily find a way it remains manageable for translators.


> Walk throughs on the other hand require a considerable code effort and have
> to be embedded in the code completely. They need an engine which can drive
> the interfaceand either feed data in or better still request the user to
> enter the data.  The one I am most familiar with is in the Flight Gear
> flight simulator on Linux. It is just like a flying instructor taking you
> through the check list before takeoff. While it would be nice I doubt if it
> would really be feasible.
> 
Agreed. Walk throughs ad described on the link David passed are not planned in 
the foreseeable future. What I was hinting at in my suggestions is more 
documentation formatted as explained in:
https://www.youtube.com/watch?
v=7amYpQWhz3o=57=PLaVkMRyQacUQYxXkzvcZJm-kc_FEJpkxK=0s

But to be clear: I won't be doing the documentation restructuring/writing, so 
neither will I dictate what format and content the guide should be. I'm fine 
with the current high level proposals.

I do care about maintainability beyond the initial restructuring/rewriting 
effort so if I find issues in that area, you'll hear me :)

In that context I think we should make documentation translation a separate 
thread. The current one is getting hard to follow.

Regards,

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

David,

Just some comments on a couple of other points: 

Embedding even the context help in the program code is not a really good
idea. It means that text cannot be edited /altered easily separately from
the program and without rebuilding the program.  My understanding is that it
can be done from a docbook that just has the links to a section which is
displayed in response to a help button being pressed or  something like a
Shift-F1 key combination while the focus is on the button/checkbox/etc that
you want help on. It could be a separate window from the main help system
which just pops up displays the information and closes when you finish (i.e
no navigation - want help on something else-click on something else and hit
shift F10 -  but pulls its text from a HTML file created from a 
docbook/asciidoc or similar source help file. It would not necessarily have
to have such a file broken up into subfiles.

The same would also be true of the Concepts guide. It could be modules
within a single file or a collection of files which can either be displayed
independently or linked together to form a full document. The existing Help
manual are organised a bit like that but the separate files for the chapters 
do not have document headers so they can't be displayed independently . What
I mean by that is you can point a browser at the derived HTML file for a
chapter and have it display just that chapter without having to load the
whole Help manual and navigate to the bit you want. In any case breaking it
into separate source files is not a high priority but it may make some sense
to have related content in its own module futher down the track. It can also
be done progressively once the content  has been rearranged.

Walk throughs on the other hand require a considerable code effort and have
to be embedded in the code completely. They need an engine which can drive
the interfaceand either feed data in or better still request the user to
enter the data.  The one I am most familiar with is in the Flight Gear
flight simulator on Linux. It is just like a flying instructor taking you
through the check list before takeoff. While it would be nice I doubt if it
would really be feasible.

David Cousens



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op dinsdag 11 september 2018 06:03:28 CEST schreef David Cousens:
> This link (http://www.sagehill.net/docbookxsl/Db5Tools.html) provides the
> mechanism for linking between different docbooks. It would probably a good
> idea to mark any  docbook links with a do not delete message for example. so
> that editors are aware they may break any linked structure,
> 
I know you can define these links in docbook. However my remark earlier in 
this thread is how will they work in practice ? How can one document on the 
system know where the other is stored ? I presume this means we should have 
strict rules about the relative locations of documents. And those should be 
communicated properly to gnucash-documentation packagers for various 
distributions. And how would those cross-references appear in our PDF/epub/
mobi versions of the documentation ?

So while I suppose this can all be solved, it will come with a few challenges 
on its own and requires coordination outside the gnucash project.

> I am willing to help with the task of reorganizing the above if the decision
> is made to go ahead.

Yay!

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

David,

I also subscribe to your manifesto:

I agree that the Concept guide should be just that. Not how to specifically
do something using Gnucash 

1. A minimal set of basic accounting concepts with reference perhaps to more
detailed material.
2. Some discussion how GnuCash implements these:
  e.g 
   a) Account register as the primary interface
  b) Transactions and splits
  c) Lots and how they apply to trading accounts and FIFO, LIFO etc

The Help can be implemented as a split between tooltips and context
sensitive help. Tooltips are not really appropriate for objects like windows
where you may be hovering in the window sometimes for extended times and
having a tooltip up would drive you mad. I think context sensitive help is
more appropriate for describing the functionality of more complex display
structures like windows. There is no difficulty I think in implementing this
from a docbook or similarly driven HTML document or set of documents. The
facilities for creating and accessing links does exist in docbooks and in
most alternatives.  It would also be possible to structure this so it was
readable as a document. I would see it as being limited fairly strongly to
the minimum necessary description function of the window, button, checkbox
etc. One thing not clear to users from a stricly functional approach is
where there may be down stream consequences of a particular choice. i.e why
would I make specific choice where there may be two or more options
available. (I think this is where the use-case/tutorial approach can be of
value e.g. a link to a recipe/tutorial where the option is used.).  Using
the info re modularity and embedding of the xml files in a link I pasted
earlier creating context sensitive help should be feasible as well as
providing access to it as a complete document. (I seem to have uncovered a
bug in bringing up the context sensitive help window at least in the Linux
version of 3.2 but that is a separate issue and is fixable)

I also agree with you about splitting off the tutorial type content from the
Concept Guide into a "How to do that using Gnucash" style section. One
reservation I have about using the wiki, although not a strong one, is that
I find navigation around the wiki can be problematical unless it has a set
of next, previous, up and top type links. One can end up somewhere along a
chain with no way of getting back quickly apart from retracing the links
using the browser back key. One other problem with a WIki for a maintenance
point of view is thatt a link to a page can be deleted and the page becomes
an orphan with no way to logically access it. A search negine will sometimes
find orphan pages in a wiki.

 It is equally doable in docbooks xml approach as a separte document. It is
possibly a bit easier to maintain and possibly provide links into it. I
think it would only require some fairly minor code changes to add extra
items to the help menu for example. 

This link (http://www.sagehill.net/docbookxsl/Db5Tools.html) provides the
mechanism for linking between different docbooks. It would probably a good
idea to mark any  docbook links with a do not delete message for example. so
that editors are aware they may break any linked structure,

I am willing to help with the task of reorganizing the above if the decision
is made to go ahead.

David Cousens





-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Frank H. Ellenberger]

Hi David Cousens,

I opened Bug 796852 - Context sensitive Help broken. Can you add the
details there?

TIA
Frank

Am 11.09.2018 um 04:13 schrieb David Cousens:
> Geert,
> 
> No, my mistake in thinking it was in yelp Geert. I was looking into 
> something else at the time and just noticed that the context Help did not
> come up in passing yesterday.  Imentioned it in the post last night without
> having checked it out fully. My apologies for that. When it happened I had
> about 10 pages open and a lot of documentation I was scanning through
> 
> The behavior is however a bit strange. If I restart GnuCash then do
> Business->Vendor->New Bill then click the Help on the dialog, no help Window
> opens. If I then close the dialog and open the Help->Contents to display the
> help window, leaving it open,  then go through the sequence
> Business->Vendor->New Bill and click the help button again the information
> on Invoices is displayed in the open help window. Close the help window then
> press the Help button on the dialog again and nothing happens again. I get
> the same behavior with the Help from the menu in the Reconcile window and
> the New Invoice, Close Book dialog etc.
> 
> It appears that there has to be a help window already open and then the
> context snesitive page can be displayed in that window, but the Help button
> in the dialog cannot initiate opening the Help Window on its own. This may
> be the designed behavvior and if so it just needs to be documented but it
> would be nice to have context help come up whether you have a help window
> open or not. I don't normally notice it because I usually use the online
> Help and Tutorial.. in a browser window. 
> 
> I am currently running a build from my local copy of the Github master. I
> haven't made any changes since getting a clean copy of the master into my PR
> and then cloning it to my PC and rebuilding it. I can pull down the tarball
> for the release version of 3.2 build it and check it as well. Linux MInt 19
> "Tara".
> 
> David
> 
> 
> 
> -
> David Cousens
> --
> Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> 

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

Geert,

It can process HTML but I haven't yet put other markup through it. I am not
sure how to batch it but there is an interface which will up load a file and
translate it and presumably allow you to save it back.  I doubt if you would
use it if you have an active translator available for a language. I think
there may also be an API but I would have to check it out

David



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

Geert,

No, my mistake in thinking it was in yelp Geert. I was looking into 
something else at the time and just noticed that the context Help did not
come up in passing yesterday.  Imentioned it in the post last night without
having checked it out fully. My apologies for that. When it happened I had
about 10 pages open and a lot of documentation I was scanning through

The behavior is however a bit strange. If I restart GnuCash then do
Business->Vendor->New Bill then click the Help on the dialog, no help Window
opens. If I then close the dialog and open the Help->Contents to display the
help window, leaving it open,  then go through the sequence
Business->Vendor->New Bill and click the help button again the information
on Invoices is displayed in the open help window. Close the help window then
press the Help button on the dialog again and nothing happens again. I get
the same behavior with the Help from the menu in the Reconcile window and
the New Invoice, Close Book dialog etc.

It appears that there has to be a help window already open and then the
context snesitive page can be displayed in that window, but the Help button
in the dialog cannot initiate opening the Help Window on its own. This may
be the designed behavvior and if so it just needs to be documented but it
would be nice to have context help come up whether you have a help window
open or not. I don't normally notice it because I usually use the online
Help and Tutorial.. in a browser window. 

I am currently running a build from my local copy of the Github master. I
haven't made any changes since getting a clean copy of the master into my PR
and then cloning it to my PC and rebuilding it. I can pull down the tarball
for the release version of 3.2 build it and check it as well. Linux MInt 19
"Tara".

David



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

Chris,

It maybe worth pursuing if libwebkit can support context sensitive help. It 
HTML Help on Windows I believe a set of
aliases mapped onto URLs for the appropriate section of HTML help files from 
the help file is generated by the processor
and then used to pull up the appropriate section of help. It would require the 
current chapter files to be broken down
into snippets in individual files which can be accessed separately or linked 
together to constitute the 
manual. Docbook has the mechanism for creating links. The downside is perhaps 
that you would have to recreate a help
viewer using it inside the gnucash code -  a lot more coding than simply 
passing a URI to the external viewer. 

I am surprised that yelp doesn't support context sensitive help. In a quick 
search yesterday I couldn't find any
reference to it or how to access it. I'll have a look at the yelp repo to see 
if it's documented there.

David Cousens

On Mon, 2018-09-10 at 19:51 +0800, Christopher Lam wrote:
> On Mon, 10 Sep 2018 at 19:31, David Cousens 
> wrote:
> 
> > 
> > One problem I see for Unix is that at present there doesn't appear to be a
> > help viewer in Unix that has support for context level help. Doc books can
> > obviously support defining links that can be accessed from help buttons or
> > a
> > key based popup help but as far as I could see yelp has no mechanism for
> > linking to them.
> > 
> 
> Is there any merit to the idea of launching documentation and
> context-sensitive help as a libwebkit tab?
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Frank H. Ellenberger]

Am 10.09.2018 um 00:32 schrieb D:
> Frank,
> 
> You raise significant points about the effect that this might have on 
> translations.
> 
> How would it be if these changes occurred in the course of a piecemeal 
> approach? In other words, if I or someone else were to essentially remove the 
> text from one document, put it in the other, and add new text at the first, 
> would that be better?

YES, and adding comments of the form

would IMHO be very helpful.

Background:
At least I use 2 kdiff3 like editor windows. In the first displaying the
changes in C since our last translation edits. In the 2., comparing the
current english with the current german version the real work happens.
The section Ids do the synchronisation in both windows.

> David

Frank

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David T. via gnucash-devel]

OK. In reply to my own message, I have paged through the Help and compared it 
to the Guide. I compiled a mapping framework from Help to the Guide, and found 
that this might not be as huge an undertaking as I initially thought.

Here are my thoughts:

1. Introduction to GnuCash  :   
Delete. The single paragraph enclosed therein is covered elsewhere.
2. Using This Document & Getting Help   :   Delete. 
This information is in the Guide.
3. Getting Started  
:   Merge into Guide 2.3 The Basics. Interface
4. GnuCash Windows & Menus Options Overview :   Merge into 
Guide 2.3 The Basics. Interface as appropriate. Retain Menus and Context Help.
5. Setting Up, Editing & Working with Accounts  :   Merge into 
Guide 3 Accounts as appropriate, except 5.4.1.1 (Online Price Retrieval) into 
Guide 9.6 Investing
6. Common Transaction Operations:   Merge 
into Guide 4 Transactions. I’ll note that the Help is more detailed than the 
Guide in this area
7. Business Features:   
Largely duplicate copy of chapter 13. Business Features.
8. Tools & Assistants   :   
Merge into various chapters based on subject—e.g., investment-oriented 
assistants get put into Guide 9 Investments.
9. Reports And Charts   :   
Delete. Guide 10 Reports covers in more detail
10. Customizing GnuCash :   Add as 
needed to new Customization chapter following Guide chapter 4.
A. GnuCash Tips and tidbits :   
Delete/Move to wiki (currently consists of Finance::Quote data which is, as we 
all know, a fast-moving target)
B. GNU Free Documentation License

As for the Guide, there are a number of bugs outstanding that point to a future 
direction for the structure there, most specifically Bug 687820, so I won’t 
address those here, except to point out that the various appendices included 
there should be moved to the wiki and maintained there.

Cheers,
David

> On Sep 10, 2018, at 11:26 AM, David T. via gnucash-devel 
>  wrote:
> 
> Dear All,
> 
> I reply to this message (even though it lacks the previous discussions for 
> context), as it is the latest in the thread. I will, however, try to take on 
> some of the issues that have gotten raised. I apologize for the length and 
> density of the reply.
> 
> *** My Documentation Manifesto ***
> 1. The Concept Guide should be the primary informational document. 
> 2. The Help should provide specific information on the functions that a given 
> on screen element serves—i.e., Contextual Help.
> 3. The wiki should give technical information and information that is only 
> applicable to specific user situations.
> 

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David T. via gnucash-devel]

Dear All,

I reply to this message (even though it lacks the previous discussions for 
context), as it is the latest in the thread. I will, however, try to take on 
some of the issues that have gotten raised. I apologize for the length and 
density of the reply.

With regard to translations, I am not informed enough of any of the issues 
involved to offer any insight. I defer to those who can speak more than one 
language using complete sentences (rather than a combination of misconjugated 
verbs, incorrect formality modes, and gestures not intended to be rude in any 
way). ;)

With regard to the idea of using multiple back end XML files, Geert is right 
that I was not talking about removing multiple back end source files (although 
I will note that having data fragmented in the sources seems to lead to 
duplication of content and effort, as different writers conceptualize the 
proper location for a given piece of information in different ways). My goal is 
to unify the narrative help into one sequence and reduce duplication and 
overlap. Bringing all the source XML files into one Frankenstein sequence might 
be a way to see the future pain, but I imagine that any such amalgamation would 
only exist for the editorial process; any final product would in all likelihood 
bear only limited similarity to this documentation monster.

As might be expected from my sending in a generic bombshell, there has been a 
lively discussion touching on a number of different aspects of the 
documentation.

At the core, my proposal has the goal of making clearer the primary purposes of 
the different types of documentation, and working to ensure that information 
gets placed in the proper place, and only the proper place. 

The article at 
https://pronovix.com/blog/overview-context-sensitive-and-embedded-help-formats 

 focuses on web modalities, but the background analysis of user 
assistance-seeking behavior is intriguing.

Currently, there is a lack of clarity in the GnuCash community on the roles of 
the different documentation, and it crops up repeatedly. Questions of 
appropriate content for the wiki, of whether information belongs in the Help or 
the Guide, etc. are all indicative of this underlying problem.

*** My Documentation Manifesto ***
1. The Concept Guide should be the primary informational document. 
2. The Help should provide specific information on the functions that a given 
on screen element serves—i.e., Contextual Help.
3. The wiki should give technical information and information that is only 
applicable to specific user situations.

With these three statements, a number of results follow. 

First, the Guide would contain most of the narrative, explanatory text covering 
how GnuCash works, and how to manage most common accounting situations. Next, 
the Help would be stripped back substantially, with most of the narrative 
content that currently resides in the Help migrated to the Guide. Third, the 
Tutorial aspects of the documentation would reside on the wiki. More on the 
Tutorial issue later.

My goal is to eliminate the situation where we document Online Banking [or 
Reconciliation, or Account Types, or Loans, or Investments, or… you get the 
idea] in every spot in the GnuCash documentation, and, just for fun, have each 
one differ just a little bit from the others, so that the user can’t be sure 
which source is the closest to accurate. 

With regard to the Help, I wonder whether there is some way to use the code 
itself to generate context help programmatically, rather than have it be a 
human-edited, git-managed document. As it stands right now, the Help kind of 
looks like someone started out that way with lists of menus and options, but 
then someone else came along and started writing text to go with those lists of 
menus. And now we have something in between. Having a 
programmatically-generated Context Help system would remove this document from 
the concerns of documenters, and once established, would only need modification 
if the interface were changed. I do not know how such a mechanism would work, 
but I imagine that it would require additional work in code to ensure that the 
proper links are embedded. I recognize that such an endeavor would be 
substantial for an application as complex as GnuCash, but I believe the payoff 
would be major.

Returning to the Tutorial issue: Geert asked me whether it was the style of the 
writing, or the content that bothered me. I think that the style was what first 
bothered me there, but as I considered it further, I felt that there were 
deeper issues embedded. Most fundamentally, I think that as currently written, 
some information about how GnuCash works is written in the *Guide* parts of the 
T, while other aspects are embedded in the *Tutorial* parts of the T 
See, for example, section 3.3 of the Guide, which includes account setup 
information that is largely 

Re: [GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op maandag 10 september 2018 15:26:19 CEST schreef David Cousens:
> Geert,
> 
> Is there not perhaps a way to leverage Google translate as a first pass to
> translate text. The result may not be colloquial and produce some
> interesting results. I have used it for Russian to English translations and
> it doesn't do too bad a job.
> https://translate.google.com/toolkit/docupload?hl=en
> 
> David

Pootle integrates this. It could indeed be one way to jump start translations. 
The technical challenges would be
- decide when to run google translate. That is how do we distinguish between 
accurate real-translator-generated translations and translations that would 
benefit from a google automatic translation. And the granularity can't be 
language. It needs to be evaluated for each and every translatable chunk (a 
paragraph? a chapter? Depends on how we decide to subdivide translatable 
text).
- how clever is google translate to leave metadata/markup untouched ?
- how to automate this ?

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

XInclude reference also modular files:

 http://sagehill.net/docbookxsl/ModularDoc.html. It should just require
using a switch  on xsltproc --xinclude when building
David



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

Geert,

Is there not perhaps a way to leverage Google translate as a first pass to
translate text. The result may not be colloquial and produce some
interesting results. I have used it for Russian to English translations and
it doesn't do too bad a job.
https://translate.google.com/toolkit/docupload?hl=en

David



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

Geert

Docbook has a mechanism for including other xlm files either by declaring an
ENTITY which maps on to the filename containing the snippet xml code. You
can then use & to include the file contents at any point. You
can also construct "header files" which contain the entity definitions which
can be included in files as required. There is another mechanism using
XInclude which apparently has some more desirable traits. I found a Stack
exchange post/article on it today which extolled the virtues of usng
Xinclude. I'll find it again and post a link.

The current source files could be easily merged into the one document as
each file in the two documents has an entity declared. By moving the entity
declarations from the Guide to the Help manual and similarly moving the
> lines in the gnucash-guide.xml  into the gnucash-help.xml file
then moving the Guide source files in with the Help source files, they would
become one document (needing some major rearrangement of course).

 An initial rearrangement looks possible by just rearranging the order of
the & statements. At the moment each file is a chapter and is
imported by the above statements.

A full rearrangement would require breaking the chapters  down into snippets
and then including them where required or in some cases just providing a
link back to where the snippet is first included.

David Cousens




-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op maandag 10 september 2018 13:51:28 CEST schreef Christopher Lam:
> On Mon, 10 Sep 2018 at 19:31, David Cousens 
> 
> wrote:
> > One problem I see for Unix is that at present there doesn't appear to be a
> > help viewer in Unix that has support for context level help. Doc books can
> > obviously support defining links that can be accessed from help buttons or
> > a
> > key based popup help but as far as I could see yelp has no mechanism for
> > linking to them.
> 
> Is there any merit to the idea of launching documentation and
> context-sensitive help as a libwebkit tab?

That is indeed what John and I have been thinking about longer term. I should 
have mentioned it. Of course we'd have to provide some sensible navigation 
options for the user (index, back/forward buttons). And no external links 
opened directly in gnucash (that would open the door for all kinds of security 
issues).

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Christopher Lam]

On Mon, 10 Sep 2018 at 19:31, David Cousens 
wrote:

>
> One problem I see for Unix is that at present there doesn't appear to be a
> help viewer in Unix that has support for context level help. Doc books can
> obviously support defining links that can be accessed from help buttons or
> a
> key based popup help but as far as I could see yelp has no mechanism for
> linking to them.
>

Is there any merit to the idea of launching documentation and
context-sensitive help as a libwebkit tab?
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op maandag 10 september 2018 13:30:20 CEST schreef David Cousens:
> One problem I see for Unix is that at present there doesn't appear to be a
> help viewer in Unix that has support for context level help. Doc books can
> obviously support defining links that can be accessed from help buttons or a
> key based popup help but as far as I could see yelp has no mechanism for
> linking to them.

I don't understand this. Do you mean that when I click on context sensitive 
help in gnucash, yelp won't show the context sensitive help for that ui 
element ?

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op zondag 9 september 2018 12:21:08 CEST schreef Frank H. Ellenberger:
> -: I18N: We will loose the current translations and probably frustrate
> the last translators and loose their readers.
> 
Absolutely true. However I don't know if that's sufficient reason to keep the 
less that satisfactory status quo.

To be honest I think this is a weakness in our tooling and one that is 
preventing us from moving forward.

> ?: Usability: Will F1 or pressing the Help button still deliver the
> right content? I know it is aslo now not always th case.
> 
If I read David's proposal carefully there remains some kind of interface 
index document (listing all ui buttons, menu items,...). But instead of having 
full documentation they would point to relevant sections in the manual. 
Assuming we can make cross-linking work, this should be covered.

On the other hand if we think of our documentation more as a clever 
composition of documentation snippets, we could also opt to compose help 
information from the same snippets that are used to compose the full manual. 
That's theory of course. I don't know if this would be possible in practice.

> Historical note: we had a GUM in version 1 and I assume there were
> reasons to break it in two parts.
> 
> > We should resolve the source-format question
> > (Docbook/Asciidoc/Docx/Markdown) before beginning actual writing.
> > 

Yes, we should (the list of flavors is endless by the way, I just ran into 
reStructuredText, yet another variation on the theme).

And even before that we should think in more detail on how to organize our 
documentation. What structure can we come up with that works for all 
contributors ? How to keep it manageable ? How to make it easy to use ?

I understand direct interaction with git is a hurdle for documentation 
contributors. I still don't have a good enough alternative so far.

And then back to translations. We have experimented with two methods so far:
- each translator manually copies files from the English documentation, 
directly translates that file itself and commits the result the the proper 
language directory.
- let gettext extract all translatable strings and offer the translator a 
message catalog to translate.

Both methods have advantages and drawbacks.
Method 1:
+ users will only get content in their language
- however that may be very incomplete (only the parts of the manual that are 
translated are presented to the user)
- it is very difficult for translators to update existing translations because 
it's hard to determine what has changed in the English language

Method 2:
+ will always provide the full documentation to the user
- large parts can be in English instead of their native language.
- documentation updates in the English language directly affect the translated 
document. For example if a paragraph has been translated and someone adds a 
comma in the the English version of the paragraph, the translated 
documentation will now show the English version instead of the native one.
+ this pickiness does help translators to easily spot which translations need 
updating

The question is, which is worse ? From a translator's point of view I would 
think the second method would be more maintainable. However how do non-native-
English users perceive a document with mixed languages ?

Again I think better tooling can help here as well. A few examples

- when composing/building the final document in method 2 we could temporarily 
remove "fuzzy" markers so that "almost good" translations are still shown to 
the user.

- again for method 2 we could annotate all improperly translated sections such 
that the final document has "Missing Translation" tags and a pointer to invite 
readers to contribute translations.

- or even better: the online documentation should be "live" editable. The 
infamous "Edit me on github" ribbons we see appear everywhere, but then 
better. Ideally a mixture between something like the Edit me... thing and 
something like Pootle's online translation editor:
http://docs.translatehouse.org/projects/pootle/en/stable-2.8.x/features/
index.html#online-translation-editor
oh and Pootle does come with git integration. Unfortunately still in beta. And 
still python2.
- pootle can be very useful on the translation side of things, but it's not 
helping with writing documentation itself. So while searching yet again for a 
possible solution I came across https://edit.php.net/ which is an online 
editor for the php documentation, which also happens to be writting in 
docbook. It's based on a few other projects such as https://codemirror.net/ an 
online text editor for lots of languages including markdown, reStructuredText 
and xml. I suspect the php team combined this with a few other bits to make it 
a docbook parser with helpful elements such as an acronym browser and an 
entity browser, syntax checking,...
- In the same category there are other online editors such as
  * https://dillinger.io/ (Markdown, github aware)
  * 

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

Thanks Geert

My apologies to David T if I misunderstood the intention re a single
document. A single document with separate sections may help to reduce
duplication, but that mainly requires editorial effort no matter whether it
is a single document or not. it would certainly help with searches.   I also
agree that there is a lot of duplication in the two manuals. 

One problem I see for Unix is that at present there doesn't appear to be a
help viewer in Unix that has support for context level help. Doc books can
obviously support defining links that can be accessed from help buttons or a
key based popup help but as far as I could see yelp has no mechanism for
linking to them.

David



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [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


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op maandag 10 september 2018 10:11:11 CEST schreef David Cousens:
> David,
> 
> As well as Frank's objections to rewriting, why does having one massive file
> necessarily improve the structure or maintainability. This is not the case
> with programming code. Docbook can include files in a far more structured
> manner than the gnucash xml sources do at the moment. I would have thought
> more modularization of the documentaion and some restructuring would
> improve the maintainability.
> 

I don't think David T meant to put everything in one single source file. I 
believe the idea is to have one single user document. So the user would only 
have one link on the website to choose from or one pdf to download to get all 
information. Internally this document will certainly still be composed of 
multiple source files.

> I think there is perhaps more need for the tutorial approach - "How to do
> this with Gnucash", particularly for newer users ,than  for  interface
> button by button functional type documentation and the latter is more useful
> when users have gained some experience and just want specific information
> on what happens when they select a particular button or menu option.
> 
I'm a big fan of use-case based documentation (or "tutorial" based). I have no 
experience with writing or maintaining such documentation though. I have 
attended a couple of presentations earlier this year on that topic. It's much 
closer to what users are typically searching for than a formal explanation of 
how each feature of gnucash works. Going into this would be a whole 
conversation on its own.

But I do follow David T's observation that there's too much duplication. The 
fact we currently maintain two fairly independent "manuals" is very likely 
conductive to this duplication.

It doesn't necessarily have to be though. If there's a strong definition of 
what goes into interface help and what goes into manual we could guard this 
off.

The proposal is to make the interface help very short, with links to relevant 
topics in the manual. Having links across documents is challenging so I can 
follow the proposal to put it all in one document. That will save us support 
questions like "the link to topic x in help topic y doesn't seem to work".

> My not particularly deep understanding of docbook  is the more the
> documentation is broken down with separate headings the more searchable it
> becomes and the more easily specific information can be located by using a
> search.

True. However this is completely tangential to how the sources are split up in 
files. This searchability comes from using appropriate tags.

Regards,

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[David Cousens]

David,

As well as Frank's objections to rewriting, why does having one massive file
necessarily improve the structure or maintainability. This is not the case
with programming code. Docbook can include files in a far more structured
manner than the gnucash xml sources do at the moment. I would have thought
more modularization of the documentaion and some restructuring would improve
the maintainability.

I think there is perhaps more need for the tutorial approach - "How to do
this with Gnucash", particularly for newer users ,than  for  interface
button by button functional type documentation and the latter is more useful
when users have gained some experience and just want specific information on
what happens when they select a particular button or menu option.

My not particularly deep understanding of docbook  is the more the
documentation is broken down with separate headings the more searchable it
becomes and the more easily specific information can be located by using a
search. The tutorial sections tend to be more narrative/recipe like in their
construction but by crossreferencing into a functional interface description
a user can access the information when they need it and bypass it if it is
not clear what is meant.


David Cousens 



-
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[D via gnucash-devel]

Frank,

You raise significant points about the effect that this might have on 
translations.

How would it be if these changes occurred in the course of a piecemeal 
approach? In other words, if I or someone else were to essentially remove the 
text from one document, put it in the other, and add new text at the first, 
would that be better?

David

On September 9, 2018, at 6:21 AM, "Frank H. Ellenberger" 
 wrote:

Hi,

Am 08.09.2018 um 17:48 schrieb John Ralls:
>> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel 
>>  wrote:
>>
>> 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).
>>
>> I do not make this suggestion lightly—I know the complexity and difficulty 
>> of such an endeavor. However, I increasingly find that the content of the 
>> Help and Guide are so inextricably enmeshed that any attempt to clean up one 
>> will have extreme impact on the other—and attempting to shepherd these 
>> changes through piecemeal is cumbersome at best. 
>>
>> Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 
>> 287. That’s over 500 pages of information—a good portion of which is 
>> duplicated across the docs. Any such rewrite would entail a HUGE effort, 
>> which is why I write this email: there is no way anyone would undertake this 
>> without knowing in advance whether the community would accept such a change 
>> at the outset.
> 
> I’ve no objection in principle.  Thorough preparation for such a rewrite 
> would also include a review of the mailing list archives and the wiki.

-: I18N: We will loose the current translations and probably frustrate
the last translators and loose their readers.

?: Usability: Will F1 or pressing the Help button still deliver the
right content? I know it is aslo now not always th case.

Historical note: we had a GUM in version 1 and I assume there were
reasons to break it in two parts.

> We should resolve the source-format question (Docbook/Asciidoc/Docx/Markdown) 
> before beginning actual writing.
> 
> It’s a pretty massive project, I think you’ll need to recruit a team.

You might also consider to choose a more recent license. But that would
mean, you must not copy

> Regards,
> John Ralls


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Frank H. Ellenberger]

Hi,

Am 08.09.2018 um 17:48 schrieb John Ralls:
>> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel 
>>  wrote:
>>
>> 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).
>>
>> I do not make this suggestion lightly—I know the complexity and difficulty 
>> of such an endeavor. However, I increasingly find that the content of the 
>> Help and Guide are so inextricably enmeshed that any attempt to clean up one 
>> will have extreme impact on the other—and attempting to shepherd these 
>> changes through piecemeal is cumbersome at best. 
>>
>> Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 
>> 287. That’s over 500 pages of information—a good portion of which is 
>> duplicated across the docs. Any such rewrite would entail a HUGE effort, 
>> which is why I write this email: there is no way anyone would undertake this 
>> without knowing in advance whether the community would accept such a change 
>> at the outset.
> 
> I’ve no objection in principle.  Thorough preparation for such a rewrite 
> would also include a review of the mailing list archives and the wiki.

-: I18N: We will loose the current translations and probably frustrate
the last translators and loose their readers.

?: Usability: Will F1 or pressing the Help button still deliver the
right content? I know it is aslo now not always th case.

Historical note: we had a GUM in version 1 and I assume there were
reasons to break it in two parts.

> We should resolve the source-format question (Docbook/Asciidoc/Docx/Markdown) 
> before beginning actual writing.
> 
> It’s a pretty massive project, I think you’ll need to recruit a team.

You might also consider to choose a more recent license. But that would
mean, you must not copy

> Regards,
> John Ralls


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[Adrien Monteleone]

David,

Count me in. (with a vote for Markdown)

Consider the idea of making the bulk of the current Help to be appendices of 
the new Manual. Many of those pages are simply reference lists of the menu 
entries.

Also, consider arranging the Manual by function rather than form. If GnuCash 
evolves to more closely follow the Gnome HIG, the UI is going to be very 
different in how it presents each function and where it appears. Arranging the 
manual this way will mesh nicely with that path and relieve the need to 
completely re-write it yet again.

Regards,
Adrien

> On Sep 8, 2018, at 10:48 AM, John Ralls  wrote:
> 
> 
> 
>> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel 
>>  wrote:
>> 
>> 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).
>> 
>> I do not make this suggestion lightly—I know the complexity and difficulty 
>> of such an endeavor. However, I increasingly find that the content of the 
>> Help and Guide are so inextricably enmeshed that any attempt to clean up one 
>> will have extreme impact on the other—and attempting to shepherd these 
>> changes through piecemeal is cumbersome at best. 
>> 
>> Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 
>> 287. That’s over 500 pages of information—a good portion of which is 
>> duplicated across the docs. Any such rewrite would entail a HUGE effort, 
>> which is why I write this email: there is no way anyone would undertake this 
>> without knowing in advance whether the community would accept such a change 
>> at the outset.
> 
> I’ve no objection in principle.  Thorough preparation for such a rewrite 
> would also include a review of the mailing list archives and the wiki.
> 
> We should resolve the source-format question (Docbook/Asciidoc/Docx/Markdown) 
> before beginning actual writing.
> 
> It’s a pretty massive project, I think you’ll need to recruit a team.
> 
> Regards,
> John Ralls
> 
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Long Term Documentation Directions

[John Ralls]

> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel 
>  wrote:
> 
> 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).
> 
> I do not make this suggestion lightly—I know the complexity and difficulty of 
> such an endeavor. However, I increasingly find that the content of the Help 
> and Guide are so inextricably enmeshed that any attempt to clean up one will 
> have extreme impact on the other—and attempting to shepherd these changes 
> through piecemeal is cumbersome at best. 
> 
> Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 287. 
> That’s over 500 pages of information—a good portion of which is duplicated 
> across the docs. Any such rewrite would entail a HUGE effort, which is why I 
> write this email: there is no way anyone would undertake this without knowing 
> in advance whether the community would accept such a change at the outset.

I’ve no objection in principle.  Thorough preparation for such a rewrite would 
also include a review of the mailing list archives and the wiki.

We should resolve the source-format question (Docbook/Asciidoc/Docx/Markdown) 
before beginning actual writing.

It’s a pretty massive project, I think you’ll need to recruit a team.

Regards,
John Ralls

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel