Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

[Geert Janssens]

Op dinsdag 21 augustus 2018 17:49:57 CEST schreef Adrien Monteleone:
> Thanks for the background info Geert,
> 
> I recall a discussion some time ago about the tools and methods used to
> generate the documentation, and I think based on that thread and the info
> you’ve just provided that the solution lies in a new method entirely.
> (frames aren’t really the best option as you noted)
> 


> I’ll try to dig up that old thread,
This comes up every now an then...

There was a long thread in 2015 suggesting asciidoc, latex or libreoffice as 
alternative formats:
https://lists.gnucash.org/pipermail/gnucash-devel/2015-August/038976.html
https://lists.gnucash.org/pipermail/gnucash-devel/2015-September/038984.html

This was preceded by another thread on this topic:
https://lists.gnucash.org/pipermail/gnucash-devel/2015-August/038952.html

And that thread referred back to a similar thread in 2013:
http://lists.gnucash.org/pipermail/gnucash-devel/2013-December/036626.html

And in May 2017 there was another foray into 'new documentation tooling' land 
as part of this thread:
https://lists.gnucash.org/pipermail/gnucash-devel/2017-May/040600.html

I'm sure there will be more of them.

> but is there a list of ’needs’ of the
> developers to use when evaluating methods?
> 
I don't think it's ever been formally written down. But here is a first list:

- it should be as easy as possible to use by non-technical people
- it should allow multiple output formats. A few the come to mind:
html, pdf, epub, mobi, windows compressed help, xml for yelp,...
- it should support both on-screen output as printable output. This is mostly 
relevant for image resolutions.
- it should support the usual typical documentation constructs, like chapters, 
sections, subsections, indexes, links, tables, images,...
- it should be manageable. That is there should be mechanisms to support 
multiple versions of one document simultaneously. A typical use case is that 
some feature gets documented that is in both the current version and the 
future one, so this document snippet should be in both versions of the 
documentation as well. While a snippet that's only for the newer version 
should only be in the future version of the documentation. And after a few 
months it should still be obvious which snippets have been integrated in which 
versions.
- I would like to see a WYSIWYM ("what you see is what you mean") kind of 
editor for the documentation process.

This is non-exhaustive and I expect the other developers may have even more 
requirements.

> The only thing I can find recently is that the intended approach was to
> create an “O’Reilly” style book, (just a goal or hard and fast
> requirement?) and I recall there needed to be a means to generate PDF,
> .mobi, and .epub versions.
> 
> As for the current method, I see docbook has something called docbook-xslt
> which is a stylesheet approach to layout and other visuals. It seems geared
> more toward print than web, but I supposed it could be used for such. This
> strikes me though as trying to find a means to keep using the proverbial
> hammer rather than a more appropriate tool. Though, I do see Gnome is still
> using Docbook and their user help is well integrated into their website as
> individual web pages, (breadcrumbs and all) and not anything resembling a
> printed page.

I believe the gnome project is using Mallard (http://projectmallard.org/). 
Aside from that they also expect there writers to work with git.

Geert


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

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

[Adrien Monteleone]

> On Aug 21, 2018, at 7:12 AM, David T.  wrote:
> 
> David,
> 
> I haven’t advocated for renaming the documents. I changed a couple of 
> headings on the main wiki page.
> 
> There are two documents, 
> 
> 1) the Help Manual
> and
> 2) the Tutorial and Concepts Guide
> 
> as outlined at gnucash.org.
> 
> One might refer to them respectively as the “Help” and the “Guide”. There is 
> no "Help Guide.”
> 
> As for Adrien’s question regarding what goes where, there was a discussion a 
> few years back on precisely this issue—i.e., on what exactly is meant by 
> "Help Manual” and “Tutorial and Concepts Guide” and what, therefore should go 
> into each document. I can’t put my hands on that thread right now, but the 
> upshot was that the Help was seen by most as the place that identifies “this 
> button does this function” kinds of instruction, while the Guide is intended 
> to contain “if I am trying to accomplish goal X, here is how to do that.” 
> These categories are admittedly fuzzy around the edges. I admit that I am 
> more of a “how do I do X” kind of person, and so have worked most on 
> upgrading the Guide.

I think John addressed this very well in the other thread about Wiki main page 
editing. His description of the two documents should probably now be put on the 
website as well.

> 
> Finally, the website was redesigned  years ago, and the 
> current generic addressing scheme was implemented at that time. I commented 
> on it at the time, but we never came to any resolutions. I suspect some kind 
> of batter and breadcrumb solution (along with a flash frying in a nice deep 
> fryer) might help with navigation. When I am directing someone to a specific 
> page in the documentation, I right-click the link to the page in question, 
> and copy  the link. That provides the full URL.

Thanks for the tip. And that is probably how David C copied that direct link. 
The picture is much clearer now.

Regards,
Adrien


> 
> David
> 
>> On Aug 20, 2018, at 7:52 PM, David Carlson  
>> wrote:
>> 
>> I too am confused now.  First, I think David > > stated in the other documentation thread that the
>> document names need to be clarified, and that may be part of why I am
>> confused.  I think that the short names seem to be Guide and Tutorial,
>> which, if they were used consistently, would work for me.  I may be wrong
>> about the names.
>> 
>> Second, I think that there may be an alias issue, and I am not sure where I
>> am sometimes because of that. In my last foray into online documentation I
>> was specifically trying to get to the current stable (Release 3) version of
>> the documentation, and when I repeat my itinerary as I tried to describe in
>> previous posts, I do end up in pages identified as ../v3/..  So I am
>> puzzled that Adrien does not seem to get to the same place, or how some of
>> my previous attempts to document the trip do not seem to be leading to
>> pages identified as ../v3/..
>> 
>> Third, I think that document title and chapter numbers do not appear on
>> every page in each form of the documentation, and that has not helped me to
>> keep track of where I am.
>> 
>> Fourth, the label on the link in the tip just below figure 4.3 of the help
>> manual is named Tutorial and Concepts Guide and it does seem to point to
>> the Tutorial ../v3/..section 4.2, so it seems correct for the current
>> document structure.
>> 
>> I am not trying to rant, just document my confusion and agreement that
>> simplification would be helpful.
>> 
>> David C
>> 
>> On Mon, Aug 20, 2018 at 4:30 PM, Adrien Monteleone <
>> adrien.montele...@lusfiber.net> wrote:
>> 
>>> Hmm.. Not sure how I missed that recently. (I’ve read it before)
>>> 
>>> But then if it’s there, I wonder why so many questions still? Perhaps the
>>> organization or presentation isn’t very discoverable? User laziness?
>>> 
>>> Also, I still don’t think after several years that I’m clear on the
>>> difference between the Help Manual and the Tutorial & Concepts Guide. I get
>>> what their names imply and I understand the explanation on the website, but
>>> here is a case of info that I would expect to find in the other document.
>>> This is info about the GUI itself, not ‘how to use’ GnuCash to accomplish
>>> an accounting task. (which the name “Tutorial & Concepts Guide” implies and
>>> even the website itself defines as the document’s function)
>>> 
>>> Should this be relocated to the Help Manual?
>>> 
>>> Regards,
>>> Adrien
>>> 
 On Aug 20, 2018, at 3:44 PM, D  wrote:
 
 And you will find said documentation in the Guide at 2.3.3.
 
 David
 
 On August 20, 2018, at 2:32 PM, Derek Atkins  wrote:
 
 
 On Mon, August 20, 2018 2:20 pm, Adrien Monteleone wrote:
> Of course, that all makes sense.
> 
> The other improvements, specifically how to resize columns, particularly
> the Description column I think should be documented. There are enough
> questions on the list about it to address the 

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

[Adrien Monteleone]

Thanks for the background info Geert,

I recall a discussion some time ago about the tools and methods used to 
generate the documentation, and I think based on that thread and the info 
you’ve just provided that the solution lies in a new method entirely. (frames 
aren’t really the best option as you noted)

I’ll try to dig up that old thread, but is there a list of ’needs’ of the 
developers to use when evaluating methods?

The only thing I can find recently is that the intended approach was to create 
an “O’Reilly” style book, (just a goal or hard and fast requirement?) and I 
recall there needed to be a means to generate PDF, .mobi, and .epub versions.

As for the current method, I see docbook has something called docbook-xslt 
which is a stylesheet approach to layout and other visuals. It seems geared 
more toward print than web, but I supposed it could be used for such. This 
strikes me though as trying to find a means to keep using the proverbial hammer 
rather than a more appropriate tool. Though, I do see Gnome is still using 
Docbook and their user help is well integrated into their website as individual 
web pages, (breadcrumbs and all) and not anything resembling a printed page.

Regards,
Adrien

> On Aug 21, 2018, at 2:46 AM, Geert Janssens  
> wrote:
> 
> Op dinsdag 21 augustus 2018 02:44:59 CEST schreef Adrien Monteleone:
>> David C,
>> 
>> So for clarification this is the first link you posted about:
>>> https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#t
>>> xns-regstyle1
>> Notice this is in the folder /docs/v3/C/gnucash-guide/
>> 
>> But the link on the Documentation page and the link you included (both in 
> that first post and in the last one) that said how you got there was this:
>>> https://www.gnucash.org/viewdoc.phtml?rev=3=C=help
>> 
>> So yes, that IS version 3 (listed here as ‘rev=3’) but that’s not the same
>> link as above. (though it might be the exact same content, I didn’t check)
>> 
>> I can’t find any way, other than typing it in directly, to get to the
>> /docs/v3/C/ directory wherein lies the /gnucash-guide/ and /gnucash-help/
>> folders and contents. All of the links on the documentation page seem to
>> point instead to the /viewdoc.phtml which never changes the URL as you
>> navigate the document. (my guess is the viewdoc.phtml template is serving
>> the pages physically located in /docs/v3/C/, we just can’t see the real
>> URL)
> 
> The viewdoc.phtml page is a first and imperfect attempt to integrate the 
> documentation in the website.
> 
> It ensures that while presenting the documentation the main website's 
> navigation menus and style are still visible. Before that page existed 
> clicking on a documentation link would suddenly remove all website 
> decorations 
> and just show you the documentation on a plain white page with no option to 
> navigate to other parts of the main website.
> 
> viewdoc.phtml is just a wrapper that opens the actual documentation in a 
> separate frame. If you ask your browser to open that frame in its own window 
> you'll see the direct links David posted here.
> 
> The use of a frame is old-fashioned and has indeed many limitations. It was 
> the only option at the time that could be implemented with reasonable effort.
> 
> Of course it would be much nicer to have bread crumbs and clear links for 
> each 
> page. And a documentation navigation menu integrated in the website's main 
> decorations.
> 
> However from how I understand this would mean to create a specialized docbook 
> style used exclusively to generate the documentation section of our website. 
> I 
> believe the way we currently generate the gnucash html documentation is not 
> fit for integration. Writing such a specialized docbook style is possible, 
> but 
> I never found time to dig in.
> 
> Regards,
> 
> Geert


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

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

[David T. via gnucash-devel]

David,

I haven’t advocated for renaming the documents. I changed a couple of headings 
on the main wiki page.

There are two documents, 

1) the Help Manual
and
2) the Tutorial and Concepts Guide

as outlined at gnucash.org .

One might refer to them respectively as the “Help” and the “Guide”. There is no 
"Help Guide.”

As for Adrien’s question regarding what goes where, there was a discussion a 
few years back on precisely this issue—i.e., on what exactly is meant by "Help 
Manual” and “Tutorial and Concepts Guide” and what, therefore should go into 
each document. I can’t put my hands on that thread right now, but the upshot 
was that the Help was seen by most as the place that identifies “this button 
does this function” kinds of instruction, while the Guide is intended to 
contain “if I am trying to accomplish goal X, here is how to do that.” These 
categories are admittedly fuzzy around the edges. I admit that I am more of a 
“how do I do X” kind of person, and so have worked most on upgrading the Guide.

Finally, the website was redesigned  years ago, and the current 
generic addressing scheme was implemented at that time. I commented on it at 
the time, but we never came to any resolutions. I suspect some kind of batter 
and breadcrumb solution (along with a flash frying in a nice deep fryer) might 
help with navigation. When I am directing someone to a specific page in the 
documentation, I right-click the link to the page in question, and copy  the 
link. That provides the full URL.

David

> On Aug 20, 2018, at 7:52 PM, David Carlson  
> wrote:
> 
> I too am confused now.  First, I think David  > stated in the other documentation thread that the
> document names need to be clarified, and that may be part of why I am
> confused.  I think that the short names seem to be Guide and Tutorial,
> which, if they were used consistently, would work for me.  I may be wrong
> about the names.
> 
> Second, I think that there may be an alias issue, and I am not sure where I
> am sometimes because of that. In my last foray into online documentation I
> was specifically trying to get to the current stable (Release 3) version of
> the documentation, and when I repeat my itinerary as I tried to describe in
> previous posts, I do end up in pages identified as ../v3/..  So I am
> puzzled that Adrien does not seem to get to the same place, or how some of
> my previous attempts to document the trip do not seem to be leading to
> pages identified as ../v3/..
> 
> Third, I think that document title and chapter numbers do not appear on
> every page in each form of the documentation, and that has not helped me to
> keep track of where I am.
> 
> Fourth, the label on the link in the tip just below figure 4.3 of the help
> manual is named Tutorial and Concepts Guide and it does seem to point to
> the Tutorial ../v3/..section 4.2, so it seems correct for the current
> document structure.
> 
> I am not trying to rant, just document my confusion and agreement that
> simplification would be helpful.
> 
> David C
> 
> On Mon, Aug 20, 2018 at 4:30 PM, Adrien Monteleone <
> adrien.montele...@lusfiber.net> wrote:
> 
>> Hmm.. Not sure how I missed that recently. (I’ve read it before)
>> 
>> But then if it’s there, I wonder why so many questions still? Perhaps the
>> organization or presentation isn’t very discoverable? User laziness?
>> 
>> Also, I still don’t think after several years that I’m clear on the
>> difference between the Help Manual and the Tutorial & Concepts Guide. I get
>> what their names imply and I understand the explanation on the website, but
>> here is a case of info that I would expect to find in the other document.
>> This is info about the GUI itself, not ‘how to use’ GnuCash to accomplish
>> an accounting task. (which the name “Tutorial & Concepts Guide” implies and
>> even the website itself defines as the document’s function)
>> 
>> Should this be relocated to the Help Manual?
>> 
>> Regards,
>> Adrien
>> 
>>> On Aug 20, 2018, at 3:44 PM, D  wrote:
>>> 
>>> And you will find said documentation in the Guide at 2.3.3.
>>> 
>>> David
>>> 
>>> On August 20, 2018, at 2:32 PM, Derek Atkins  wrote:
>>> 
>>> 
>>> On Mon, August 20, 2018 2:20 pm, Adrien Monteleone wrote:
 Of course, that all makes sense.
 
 The other improvements, specifically how to resize columns, particularly
 the Description column I think should be documented. There are enough
 questions on the list about it to address the topic.
>>> 
>>> Absolutely!
>>> 
 Regards,
 Adrien
>>> 
 Please remember to CC this list on all your replies.
 You can do this by using Reply-To-List or Reply-All.
>>> 
>>> -derek
>>> --
>>>  Derek Atkins 617-623-3745
>>>  de...@ihtfp.com www.ihtfp.com
>>>  Computer and Internet Security Consultant
>> 
>> ___
>> gnucash-devel mailing list
>> gnucash-devel@gnucash.org
>> 

Re: [GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

[Geert Janssens]

Op dinsdag 21 augustus 2018 02:44:59 CEST schreef Adrien Monteleone:
> David C,
> 
> So for clarification this is the first link you posted about:
> > https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#t
> > xns-regstyle1
> Notice this is in the folder /docs/v3/C/gnucash-guide/
> 
> But the link on the Documentation page and the link you included (both in 
that first post and in the last one) that said how you got there was this:
> > https://www.gnucash.org/viewdoc.phtml?rev=3=C=help
> 
> So yes, that IS version 3 (listed here as ‘rev=3’) but that’s not the same
> link as above. (though it might be the exact same content, I didn’t check)
> 
> I can’t find any way, other than typing it in directly, to get to the
> /docs/v3/C/ directory wherein lies the /gnucash-guide/ and /gnucash-help/
> folders and contents. All of the links on the documentation page seem to
> point instead to the /viewdoc.phtml which never changes the URL as you
> navigate the document. (my guess is the viewdoc.phtml template is serving
> the pages physically located in /docs/v3/C/, we just can’t see the real
> URL)

The viewdoc.phtml page is a first and imperfect attempt to integrate the 
documentation in the website.

It ensures that while presenting the documentation the main website's 
navigation menus and style are still visible. Before that page existed 
clicking on a documentation link would suddenly remove all website decorations 
and just show you the documentation on a plain white page with no option to 
navigate to other parts of the main website.

viewdoc.phtml is just a wrapper that opens the actual documentation in a 
separate frame. If you ask your browser to open that frame in its own window 
you'll see the direct links David posted here.

The use of a frame is old-fashioned and has indeed many limitations. It was 
the only option at the time that could be implemented with reasonable effort.

Of course it would be much nicer to have bread crumbs and clear links for each 
page. And a documentation navigation menu integrated in the website's main 
decorations.

However from how I understand this would mean to create a specialized docbook 
style used exclusively to generate the documentation section of our website. I 
believe the way we currently generate the gnucash html documentation is not 
fit for integration. Writing such a specialized docbook style is possible, but 
I never found time to dig in.

Regards,

Geert



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