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

classic Classic list List threaded Threaded
36 messages Options
12
Reply | Threaded
Open this post in threaded view
|

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

Adrien Monteleone-2
David,

The confusion as to which document you were in I think is that the link text says ‘gnucash-guide’. There are also several references scattered on the website/wiki that refer to the ‘Help Guide’ though it appears the Documentation page calls it the ‘Help Manual’. That folder name I should think is a bug.

How did you get to that /docs/v3 link? I can’t find any path to it from the website. The links I find are all /viewdoc links which don’t tell me where I am. (at least not in the URL, just as you discovered - which brings up another navigation bug, the pages have no indication of what document you are viewing)

Also, I’ve changed the subject for you, and moved it to gnucash-devel. (I thought about doing the same on the last reply, I suppose the thread is officially hijacked now)

In Gmail, in the reply box, there is a down arrow next to the reply left-pointing arrow. (just to the left of the recipient(s)) Click it for a context menu and use “Edit Subject”

Regards,
Adrien



> On Aug 20, 2018, at 12:04 PM, David Carlson <[hidden email]> wrote:
>
> Adrien,
>
> Thank you for your research and detailed response. 🙂
> I fully agree with your conclusions.
>
>
> I got the reference to section 4.2 directly from https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#txns-regstyle1 which I arrived at when I followed the link called " Tutorial and Concepts Guide, Choosing a Register Style). " in https://www.gnucash.org/viewdoc.phtml?doc=help.  Naturally, I thought I was in the Tutorial...
>
> David C
>
> On Mon, Aug 20, 2018 at 11:45 AM, Adrien Monteleone <[hidden email]> wrote:
> I’ve never seen any documentation on it. I only confirmed it’s there after I read Derek’s comment and expanded the column myself to see it.
>
> I just did a search of the GnuCash site, wiki and html docs and I don’t see anything on the column, other than a pair of IRC logs from 2009 where someone asked what it was for, and a couple of hits (appears duplicated) documenting commits from 2017-09-4. I didn’t read the commit itself, but it was summarized by Robert Fewell as “Add a heading for the Rate column.”
>
> Concerning where to put the info, I’m not sure the Tutorial is the right place. (there is no 4.2, for example)
>
> However, the help guide has 4.3.5 List of Transactions which documents the column headings. I think if that section were more detailed with screenshots, lots of questions could be answered or even avoided.
>
> Some things to add here:
>
> The ability to resize columns and an explanation of how the Description column is special and how resizing works.
>
> An explanation with screenshots of the different types of registers showing the respective columns. (unless they are all the same, save terminology choices, then you’d only need one screenshot)
>
> An explanation of the formal vs. non-formal labels for each account type. (a full listing of what the non-formal labels are for each type)
>
> Screenshots depicting each of the modes: single-line, double-line, transaction journal.
>
> An explanation of what each cell in the transaction is for. (many don’t know the utilit(ies) of NUM or Action for example.) Not everything is self-evident. Perhaps here include a link to a special wiki page or to Using GnuCash where the different ’tricks’ for using those and other fields to accomplish user specific goals are (or should be) documented.
>
> I would be happy to get set up for editing and start on this unless you already planned on running with it.
>
> Finally, “Tutorial & Concepts Guide” is a bit winded. Could it simply be “Tutorial” or “Using GnuCash”? (and then incorporate any ‘official’ methods from that wiki page into the document, with a link to that page for the non-standard methods)
>
> Regards,
> Adrien
>
> > On Aug 20, 2018, at 10:57 AM, David Carlson <[hidden email]> wrote:
> >
> > I just tried to find reference to the rate field in the Tutorial and I found nothing.
> >
> > I think it should probably be mentioned in chapter 4 section 4.2.  That section even fails to explain single line vs two line view or dragging around field widths, so it has a long way to go before it could describe the presence of the rate field and how to access it.
> >
> > Is this information posted elsewhere?
> >
> > David C
> >
> > On Mon, Aug 20, 2018, 9:44 AM Adrien Monteleone <[hidden email]> wrote:
> > It’s still there as of 3.2.
> >
> > Regards,
> > Adrien
> >
> > > On Aug 20, 2018, at 9:17 AM, Derek Atkins <[hidden email]> wrote:
> > >
> > > John Ralls <[hidden email]> writes:
> > >
> > >> Graham,
> > >>
> > >> "Transfer" is short for "Transfer Account" and is the field where the
> > >> "other" account--other than the one in the current register--is
> > >> set. It's often called the "account" field in casual use.
> > >>
> > >> I think GTI made a translation error, the "rate" field is probably
> > >> "price" on a stock/mutual fund register, which has two more columns
> > >> than the other registers.
> > >
> > > No, there is (unless it was removed) a "RATE" field to the right of the
> > > balance column.  It's a "hidden" column, with a default width of one
> > > pixel, which is (was?) used for the exchange-rate handling of
> > > multi-currency transactions/splits.
> > >
> > >> 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, SB '93 MIT EE, SM '95 MIT Media Laboratory
> > >       Member, MIT Student Information Processing Board  (SIPB)
> > >       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
> > >       [hidden email]                        PGP key available
> > > _______________________________________________
> > > gnucash-user mailing list
> > > [hidden email]
> > > To update your subscription preferences or to unsubscribe:
> > > https://lists.gnucash.org/mailman/listinfo/gnucash-user
> > > If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
> > > -----
> > > Please remember to CC this list on all your replies.
> > > You can do this by using Reply-To-List or Reply-All.
> > >
> >
> >
> > _______________________________________________
> > gnucash-user mailing list
> > [hidden email]
> > To update your subscription preferences or to unsubscribe:
> > https://lists.gnucash.org/mailman/listinfo/gnucash-user
> > If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
> > -----
> > Please remember to CC this list on all your replies.
> > You can do this by using Reply-To-List or Reply-All.
>
>
> _______________________________________________
> gnucash-user mailing list
> [hidden email]
> To update your subscription preferences or to unsubscribe:
> https://lists.gnucash.org/mailman/listinfo/gnucash-user
> If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
> -----
> Please remember to CC this list on all your replies.
> You can do this by using Reply-To-List or Reply-All.
>


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

Adrien Monteleone-2
I just filed: https://bugs.gnucash.org/show_bug.cgi?id=796823

On the title issue as that’s a basic website usability bug.

I’ll wait for someone else to chime in on the case of the gnucash-guide folder.

Regards,
Adrien

> On Aug 20, 2018, at 1:06 PM, Adrien Monteleone <[hidden email]> wrote:
>
> David,
>
> The confusion as to which document you were in I think is that the link text says ‘gnucash-guide’. There are also several references scattered on the website/wiki that refer to the ‘Help Guide’ though it appears the Documentation page calls it the ‘Help Manual’. That folder name I should think is a bug.
>
> How did you get to that /docs/v3 link? I can’t find any path to it from the website. The links I find are all /viewdoc links which don’t tell me where I am. (at least not in the URL, just as you discovered - which brings up another navigation bug, the pages have no indication of what document you are viewing)
>
> Also, I’ve changed the subject for you, and moved it to gnucash-devel. (I thought about doing the same on the last reply, I suppose the thread is officially hijacked now)
>
> In Gmail, in the reply box, there is a down arrow next to the reply left-pointing arrow. (just to the left of the recipient(s)) Click it for a context menu and use “Edit Subject”
>
> Regards,
> Adrien
>
>
>
>> On Aug 20, 2018, at 12:04 PM, David Carlson <[hidden email]> wrote:
>>
>> Adrien,
>>
>> Thank you for your research and detailed response. 🙂
>> I fully agree with your conclusions.
>>
>>
>> I got the reference to section 4.2 directly from https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#txns-regstyle1 which I arrived at when I followed the link called " Tutorial and Concepts Guide, Choosing a Register Style). " in https://www.gnucash.org/viewdoc.phtml?doc=help.  Naturally, I thought I was in the Tutorial...
>>
>> David C
>>
>> On Mon, Aug 20, 2018 at 11:45 AM, Adrien Monteleone <[hidden email]> wrote:
>> I’ve never seen any documentation on it. I only confirmed it’s there after I read Derek’s comment and expanded the column myself to see it.
>>
>> I just did a search of the GnuCash site, wiki and html docs and I don’t see anything on the column, other than a pair of IRC logs from 2009 where someone asked what it was for, and a couple of hits (appears duplicated) documenting commits from 2017-09-4. I didn’t read the commit itself, but it was summarized by Robert Fewell as “Add a heading for the Rate column.”
>>
>> Concerning where to put the info, I’m not sure the Tutorial is the right place. (there is no 4.2, for example)
>>
>> However, the help guide has 4.3.5 List of Transactions which documents the column headings. I think if that section were more detailed with screenshots, lots of questions could be answered or even avoided.
>>
>> Some things to add here:
>>
>> The ability to resize columns and an explanation of how the Description column is special and how resizing works.
>>
>> An explanation with screenshots of the different types of registers showing the respective columns. (unless they are all the same, save terminology choices, then you’d only need one screenshot)
>>
>> An explanation of the formal vs. non-formal labels for each account type. (a full listing of what the non-formal labels are for each type)
>>
>> Screenshots depicting each of the modes: single-line, double-line, transaction journal.
>>
>> An explanation of what each cell in the transaction is for. (many don’t know the utilit(ies) of NUM or Action for example.) Not everything is self-evident. Perhaps here include a link to a special wiki page or to Using GnuCash where the different ’tricks’ for using those and other fields to accomplish user specific goals are (or should be) documented.
>>
>> I would be happy to get set up for editing and start on this unless you already planned on running with it.
>>
>> Finally, “Tutorial & Concepts Guide” is a bit winded. Could it simply be “Tutorial” or “Using GnuCash”? (and then incorporate any ‘official’ methods from that wiki page into the document, with a link to that page for the non-standard methods)
>>
>> Regards,
>> Adrien
>>
>>> On Aug 20, 2018, at 10:57 AM, David Carlson <[hidden email]> wrote:
>>>
>>> I just tried to find reference to the rate field in the Tutorial and I found nothing.
>>>
>>> I think it should probably be mentioned in chapter 4 section 4.2.  That section even fails to explain single line vs two line view or dragging around field widths, so it has a long way to go before it could describe the presence of the rate field and how to access it.
>>>
>>> Is this information posted elsewhere?
>>>
>>> David C
>>>
>>> On Mon, Aug 20, 2018, 9:44 AM Adrien Monteleone <[hidden email]> wrote:
>>> It’s still there as of 3.2.
>>>
>>> Regards,
>>> Adrien
>>>
>>>> On Aug 20, 2018, at 9:17 AM, Derek Atkins <[hidden email]> wrote:
>>>>
>>>> John Ralls <[hidden email]> writes:
>>>>
>>>>> Graham,
>>>>>
>>>>> "Transfer" is short for "Transfer Account" and is the field where the
>>>>> "other" account--other than the one in the current register--is
>>>>> set. It's often called the "account" field in casual use.
>>>>>
>>>>> I think GTI made a translation error, the "rate" field is probably
>>>>> "price" on a stock/mutual fund register, which has two more columns
>>>>> than the other registers.
>>>>
>>>> No, there is (unless it was removed) a "RATE" field to the right of the
>>>> balance column.  It's a "hidden" column, with a default width of one
>>>> pixel, which is (was?) used for the exchange-rate handling of
>>>> multi-currency transactions/splits.
>>>>
>>>>> 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, SB '93 MIT EE, SM '95 MIT Media Laboratory
>>>>      Member, MIT Student Information Processing Board  (SIPB)
>>>>      URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
>>>>      [hidden email]                        PGP key available
>>>> _______________________________________________
>>>> gnucash-user mailing list
>>>> [hidden email]
>>>> To update your subscription preferences or to unsubscribe:
>>>> https://lists.gnucash.org/mailman/listinfo/gnucash-user
>>>> If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
>>>> -----
>>>> Please remember to CC this list on all your replies.
>>>> You can do this by using Reply-To-List or Reply-All.
>>>>
>>>
>>>
>>> _______________________________________________
>>> gnucash-user mailing list
>>> [hidden email]
>>> To update your subscription preferences or to unsubscribe:
>>> https://lists.gnucash.org/mailman/listinfo/gnucash-user
>>> If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
>>> -----
>>> Please remember to CC this list on all your replies.
>>> You can do this by using Reply-To-List or Reply-All.
>>
>>
>> _______________________________________________
>> gnucash-user mailing list
>> [hidden email]
>> To update your subscription preferences or to unsubscribe:
>> https://lists.gnucash.org/mailman/listinfo/gnucash-user
>> If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
>> -----
>> Please remember to CC this list on all your replies.
>> You can do this by using Reply-To-List or Reply-All.
>>
>


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

David Carlson-4
In reply to this post by Adrien Monteleone-2
OK.

For my complete itinerary, I started at the GnuCash home page
https://www.gnucash.org/.
Clicked on Downloads > Documentation in the left column
https://www.gnucash.org/docs.phtml
from there I scrolled down the right to GnuCash v3 (current stable release)
then I selected Download Stable Help Manual English Browse Documentation
Online "
  https://www.gnucash.org/viewdoc.phtml?rev=3&lang=C&doc=help

There is where I found the incorrectly titled and badly worded link.

Also, I am still using the aout to be replaced Gmail version on the
internet, and I do nt see what you described by the reply arrow, although
my memory tells me that it used to be there.

David C


On Mon, Aug 20, 2018 at 1:06 PM, Adrien Monteleone <
[hidden email]> wrote:

> David,
>
> The confusion as to which document you were in I think is that the link
> text says ‘gnucash-guide’. There are also several references scattered on
> the website/wiki that refer to the ‘Help Guide’ though it appears the
> Documentation page calls it the ‘Help Manual’. That folder name I should
> think is a bug.
>
> How did you get to that /docs/v3 link? I can’t find any path to it from
> the website. The links I find are all /viewdoc links which don’t tell me
> where I am. (at least not in the URL, just as you discovered - which brings
> up another navigation bug, the pages have no indication of what document
> you are viewing)
>
> Also, I’ve changed the subject for you, and moved it to gnucash-devel. (I
> thought about doing the same on the last reply, I suppose the thread is
> officially hijacked now)
>
> In Gmail, in the reply box, there is a down arrow next to the reply
> left-pointing arrow. (just to the left of the recipient(s)) Click it for a
> context menu and use “Edit Subject”
>
> Regards,
> Adrien
>
>
>
> > On Aug 20, 2018, at 12:04 PM, David Carlson <[hidden email]>
> wrote:
> >
> > Adrien,
> >
> > Thank you for your research and detailed response. 🙂
> > I fully agree with your conclusions.
> >
> >
> > I got the reference to section 4.2 directly from
> https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-
> register-oview.html#txns-regstyle1 which I arrived at when I followed the
> link called " Tutorial and Concepts Guide, Choosing a Register Style). " in
> https://www.gnucash.org/viewdoc.phtml?doc=help.  Naturally, I thought I
> was in the Tutorial...
> >
> > David C
> >
> > On Mon, Aug 20, 2018 at 11:45 AM, Adrien Monteleone <
> [hidden email]> wrote:
> > I’ve never seen any documentation on it. I only confirmed it’s there
> after I read Derek’s comment and expanded the column myself to see it.
> >
> > I just did a search of the GnuCash site, wiki and html docs and I don’t
> see anything on the column, other than a pair of IRC logs from 2009 where
> someone asked what it was for, and a couple of hits (appears duplicated)
> documenting commits from 2017-09-4. I didn’t read the commit itself, but it
> was summarized by Robert Fewell as “Add a heading for the Rate column.”
> >
> > Concerning where to put the info, I’m not sure the Tutorial is the right
> place. (there is no 4.2, for example)
> >
> > However, the help guide has 4.3.5 List of Transactions which documents
> the column headings. I think if that section were more detailed with
> screenshots, lots of questions could be answered or even avoided.
> >
> > Some things to add here:
> >
> > The ability to resize columns and an explanation of how the Description
> column is special and how resizing works.
> >
> > An explanation with screenshots of the different types of registers
> showing the respective columns. (unless they are all the same, save
> terminology choices, then you’d only need one screenshot)
> >
> > An explanation of the formal vs. non-formal labels for each account
> type. (a full listing of what the non-formal labels are for each type)
> >
> > Screenshots depicting each of the modes: single-line, double-line,
> transaction journal.
> >
> > An explanation of what each cell in the transaction is for. (many don’t
> know the utilit(ies) of NUM or Action for example.) Not everything is
> self-evident. Perhaps here include a link to a special wiki page or to
> Using GnuCash where the different ’tricks’ for using those and other fields
> to accomplish user specific goals are (or should be) documented.
> >
> > I would be happy to get set up for editing and start on this unless you
> already planned on running with it.
> >
> > Finally, “Tutorial & Concepts Guide” is a bit winded. Could it simply be
> “Tutorial” or “Using GnuCash”? (and then incorporate any ‘official’ methods
> from that wiki page into the document, with a link to that page for the
> non-standard methods)
> >
> > Regards,
> > Adrien
> >
> > > On Aug 20, 2018, at 10:57 AM, David Carlson <
> [hidden email]> wrote:
> > >
> > > I just tried to find reference to the rate field in the Tutorial and I
> found nothing.
> > >
> > > I think it should probably be mentioned in chapter 4 section 4.2.
> That section even fails to explain single line vs two line view or dragging
> around field widths, so it has a long way to go before it could describe
> the presence of the rate field and how to access it.
> > >
> > > Is this information posted elsewhere?
> > >
> > > David C
> > >
> > > On Mon, Aug 20, 2018, 9:44 AM Adrien Monteleone <
> [hidden email]> wrote:
> > > It’s still there as of 3.2.
> > >
> > > Regards,
> > > Adrien
> > >
> > > > On Aug 20, 2018, at 9:17 AM, Derek Atkins <[hidden email]> wrote:
> > > >
> > > > John Ralls <[hidden email]> writes:
> > > >
> > > >> Graham,
> > > >>
> > > >> "Transfer" is short for "Transfer Account" and is the field where
> the
> > > >> "other" account--other than the one in the current register--is
> > > >> set. It's often called the "account" field in casual use.
> > > >>
> > > >> I think GTI made a translation error, the "rate" field is probably
> > > >> "price" on a stock/mutual fund register, which has two more columns
> > > >> than the other registers.
> > > >
> > > > No, there is (unless it was removed) a "RATE" field to the right of
> the
> > > > balance column.  It's a "hidden" column, with a default width of one
> > > > pixel, which is (was?) used for the exchange-rate handling of
> > > > multi-currency transactions/splits.
> > > >
> > > >> 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, SB '93 MIT EE, SM '95 MIT Media Laboratory
> > > >       Member, MIT Student Information Processing Board  (SIPB)
> > > >       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
> > > >       [hidden email]                        PGP key available
> > > > _______________________________________________
> > > > gnucash-user mailing list
> > > > [hidden email]
> > > > To update your subscription preferences or to unsubscribe:
> > > > https://lists.gnucash.org/mailman/listinfo/gnucash-user
> > > > If you are using Nabble or Gmane, please see
> https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
> > > > -----
> > > > Please remember to CC this list on all your replies.
> > > > You can do this by using Reply-To-List or Reply-All.
> > > >
> > >
> > >
> > > _______________________________________________
> > > gnucash-user mailing list
> > > [hidden email]
> > > To update your subscription preferences or to unsubscribe:
> > > https://lists.gnucash.org/mailman/listinfo/gnucash-user
> > > If you are using Nabble or Gmane, please see
> https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
> > > -----
> > > Please remember to CC this list on all your replies.
> > > You can do this by using Reply-To-List or Reply-All.
> >
> >
> > _______________________________________________
> > gnucash-user mailing list
> > [hidden email]
> > To update your subscription preferences or to unsubscribe:
> > https://lists.gnucash.org/mailman/listinfo/gnucash-user
> > If you are using Nabble or Gmane, please see
> https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
> > -----
> > Please remember to CC this list on all your replies.
> > You can do this by using Reply-To-List or Reply-All.
> >
>
>
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

image.png (2K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Adrien Monteleone-2
Strange, I followed that path and I still only get /viewdoc links. I can’t seem to hit the /docs/v3 section of the site. (notice your link is also to the /viewdoc URL, not /docs/v3)

Anyway, as for Gmail, it’s there, you have to click in the reply box to start your reply for it to appear. (I tested that on both the older and the newer version of Gmail before my last reply) You can also use the drop down in the upper right of the message with the same arrow which will move your keyboard focus to the reply box. (same as clicking in it directly)

Regards,
Adrien

> On Aug 20, 2018, at 1:54 PM, David Carlson <[hidden email]> wrote:
>
> OK.
>
> For my complete itinerary, I started at the GnuCash home page https://www.gnucash.org/.
> Clicked on Downloads > Documentation in the left column https://www.gnucash.org/docs.phtml
> from there I scrolled down the right to
> GnuCash v3 (current stable release)
>
> then I selected Download Stable Help Manual English Browse Documentation Online "
> <image.png>  https://www.gnucash.org/viewdoc.phtml?rev=3&lang=C&doc=help
>
> There is where I found the incorrectly titled and badly worded link.
>
> Also, I am still using the aout to be replaced Gmail version on the internet, and I do nt see what you described by the reply arrow, although my memory tells me that it used to be there.
>
> David C
>
>
> On Mon, Aug 20, 2018 at 1:06 PM, Adrien Monteleone <[hidden email]> wrote:
> David,
>
> The confusion as to which document you were in I think is that the link text says ‘gnucash-guide’. There are also several references scattered on the website/wiki that refer to the ‘Help Guide’ though it appears the Documentation page calls it the ‘Help Manual’. That folder name I should think is a bug.
>
> How did you get to that /docs/v3 link? I can’t find any path to it from the website. The links I find are all /viewdoc links which don’t tell me where I am. (at least not in the URL, just as you discovered - which brings up another navigation bug, the pages have no indication of what document you are viewing)
>
> Also, I’ve changed the subject for you, and moved it to gnucash-devel. (I thought about doing the same on the last reply, I suppose the thread is officially hijacked now)
>
> In Gmail, in the reply box, there is a down arrow next to the reply left-pointing arrow. (just to the left of the recipient(s)) Click it for a context menu and use “Edit Subject”
>
> Regards,
> Adrien
>
>
>
> > On Aug 20, 2018, at 12:04 PM, David Carlson <[hidden email]> wrote:
> >
> > Adrien,
> >
> > Thank you for your research and detailed response. 🙂
> > I fully agree with your conclusions.
> >
> >
> > I got the reference to section 4.2 directly from https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#txns-regstyle1 which I arrived at when I followed the link called " Tutorial and Concepts Guide, Choosing a Register Style). " in https://www.gnucash.org/viewdoc.phtml?doc=help.  Naturally, I thought I was in the Tutorial...
> >
> > David C
> >
> > On Mon, Aug 20, 2018 at 11:45 AM, Adrien Monteleone <[hidden email]> wrote:
> > I’ve never seen any documentation on it. I only confirmed it’s there after I read Derek’s comment and expanded the column myself to see it.
> >
> > I just did a search of the GnuCash site, wiki and html docs and I don’t see anything on the column, other than a pair of IRC logs from 2009 where someone asked what it was for, and a couple of hits (appears duplicated) documenting commits from 2017-09-4. I didn’t read the commit itself, but it was summarized by Robert Fewell as “Add a heading for the Rate column.”
> >
> > Concerning where to put the info, I’m not sure the Tutorial is the right place. (there is no 4.2, for example)
> >
> > However, the help guide has 4.3.5 List of Transactions which documents the column headings. I think if that section were more detailed with screenshots, lots of questions could be answered or even avoided.
> >
> > Some things to add here:
> >
> > The ability to resize columns and an explanation of how the Description column is special and how resizing works.
> >
> > An explanation with screenshots of the different types of registers showing the respective columns. (unless they are all the same, save terminology choices, then you’d only need one screenshot)
> >
> > An explanation of the formal vs. non-formal labels for each account type. (a full listing of what the non-formal labels are for each type)
> >
> > Screenshots depicting each of the modes: single-line, double-line, transaction journal.
> >
> > An explanation of what each cell in the transaction is for. (many don’t know the utilit(ies) of NUM or Action for example.) Not everything is self-evident. Perhaps here include a link to a special wiki page or to Using GnuCash where the different ’tricks’ for using those and other fields to accomplish user specific goals are (or should be) documented.
> >
> > I would be happy to get set up for editing and start on this unless you already planned on running with it.
> >
> > Finally, “Tutorial & Concepts Guide” is a bit winded. Could it simply be “Tutorial” or “Using GnuCash”? (and then incorporate any ‘official’ methods from that wiki page into the document, with a link to that page for the non-standard methods)
> >
> > Regards,
> > Adrien
> >
> > > On Aug 20, 2018, at 10:57 AM, David Carlson <[hidden email]> wrote:
> > >
> > > I just tried to find reference to the rate field in the Tutorial and I found nothing.
> > >
> > > I think it should probably be mentioned in chapter 4 section 4.2.  That section even fails to explain single line vs two line view or dragging around field widths, so it has a long way to go before it could describe the presence of the rate field and how to access it.
> > >
> > > Is this information posted elsewhere?
> > >
> > > David C
> > >
> > > On Mon, Aug 20, 2018, 9:44 AM Adrien Monteleone <[hidden email]> wrote:
> > > It’s still there as of 3.2.
> > >
> > > Regards,
> > > Adrien
> > >
> > > > On Aug 20, 2018, at 9:17 AM, Derek Atkins <[hidden email]> wrote:
> > > >
> > > > John Ralls <[hidden email]> writes:
> > > >
> > > >> Graham,
> > > >>
> > > >> "Transfer" is short for "Transfer Account" and is the field where the
> > > >> "other" account--other than the one in the current register--is
> > > >> set. It's often called the "account" field in casual use.
> > > >>
> > > >> I think GTI made a translation error, the "rate" field is probably
> > > >> "price" on a stock/mutual fund register, which has two more columns
> > > >> than the other registers.
> > > >
> > > > No, there is (unless it was removed) a "RATE" field to the right of the
> > > > balance column.  It's a "hidden" column, with a default width of one
> > > > pixel, which is (was?) used for the exchange-rate handling of
> > > > multi-currency transactions/splits.
> > > >
> > > >> 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, SB '93 MIT EE, SM '95 MIT Media Laboratory
> > > >       Member, MIT Student Information Processing Board  (SIPB)
> > > >       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
> > > >       [hidden email]                        PGP key available
> > > > _______________________________________________
> > > > gnucash-user mailing list
> > > > [hidden email]
> > > > To update your subscription preferences or to unsubscribe:
> > > > https://lists.gnucash.org/mailman/listinfo/gnucash-user
> > > > If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
> > > > -----
> > > > Please remember to CC this list on all your replies.
> > > > You can do this by using Reply-To-List or Reply-All.
> > > >
> > >
> > >
> > > _______________________________________________
> > > gnucash-user mailing list
> > > [hidden email]
> > > To update your subscription preferences or to unsubscribe:
> > > https://lists.gnucash.org/mailman/listinfo/gnucash-user
> > > If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
> > > -----
> > > Please remember to CC this list on all your replies.
> > > You can do this by using Reply-To-List or Reply-All.
> >
> >
> > _______________________________________________
> > gnucash-user mailing list
> > [hidden email]
> > To update your subscription preferences or to unsubscribe:
> > https://lists.gnucash.org/mailman/listinfo/gnucash-user
> > If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information.
> > -----
> > Please remember to CC this list on all your replies.
> > You can do this by using Reply-To-List or Reply-All.
> >
>
>
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

Adrien Monteleone-2
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 <[hidden email]> 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 <[hidden email]> 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
>       [hidden email]             www.ihtfp.com
>       Computer and Internet Security Consultant

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

David Carlson-4
I too am confused now.  First, I think David <[hidden email]
<[hidden email]>> 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 <
[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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
> >       [hidden email]             www.ihtfp.com
> >       Computer and Internet Security Consultant
>
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

Adrien Monteleone-2
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#txns-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&lang=C&doc=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)

------------

And now after I backed up a few directories from the first link above, I see regardless, *I* was in the wrong place. I didn’t see a ‘4.3' because I was looking at the section numbers which are roman numerals, not the chapter numbers. Section IV in the Guide are for the Appendices which are organized by letters. The only notation I saw then for 4.3 was in the Help Manual, which is where my confusion came from. (but that really is where I think this info should be - see my previous comment)

And sure enough there is https://www.gnucash.org/docs/v3/C/gnucash-help/ which I would have expected to see.

So, we can put aside the naming of the folder since that’s correct. But what certainly would be helpful is if the page itself indicated which document you were viewing. That bug is still there.

Regards,
Adrien


> On Aug 20, 2018, at 6:52 PM, David Carlson <[hidden email]> wrote:
>
> I too am confused now.  First, I think David <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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
> >       [hidden email]             www.ihtfp.com
> >       Computer and Internet Security Consultant
>
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

David Carlson-4
I will try inline editing, even though it is very difficult in Gmail....


David C

On Mon, Aug 20, 2018 at 7:44 PM, Adrien Monteleone <
[hidden email]> wrote:

> 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#txns-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&lang=C&doc=help


When I follow that link the url is not the same as when I go down the tree
through the online help.   That must be why I thought there were aliases
involved and why it appeared to me that you were not seeing the same
material.  It appears that the modifiers doc=help and doc=guide in phtml
point indirectly to the proper directories.  Thus, the correct (at this
time) short names are help and guide.  I would find it easier if they were
changed to something more intuitive such as help and tutorial.  I will
leave that part of the discussion to the other thread.



>
> 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)
>
> ------------
>
> And now after I backed up a few directories from the first link above, I
> see regardless, *I* was in the wrong place. I didn’t see a ‘4.3' because I
> was looking at the section numbers which are roman numerals, not the
> chapter numbers. Section IV in the Guide are for the Appendices which are
> organized by letters. The only notation I saw then for 4.3 was in the Help
> Manual, which is where my confusion came from. (but that really is where I
> think this info should be - see my previous comment)
>
> And sure enough there is https://www.gnucash.org/docs/v3/C/gnucash-help/
> which I would have expected to see.
>
> So, we can put aside the naming of the folder since that’s correct. But
> what certainly would be helpful is if the page itself indicated which
> document you were viewing. That bug is still there.
>

Yes, I agree.



> Regards,
> Adrien
>
>
> > On Aug 20, 2018, at 6:52 PM, David Carlson <[hidden email]>
> wrote:
> >
> > I too am confused now.  First, I think David <[hidden email]>
> 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 <
> [hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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
> > >       [hidden email]             www.ihtfp.com
> > >       Computer and Internet Security Consultant
> >
> > _______________________________________________
> > gnucash-devel mailing list
> > [hidden email]
> > https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> >
>
>
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

Geert Janssens-4
In reply to this post by Adrien Monteleone-2
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&lang=C&doc=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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

GnuCash - Dev mailing list
In reply to this post by David Carlson-4
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 <http://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 <mumble-mumble> 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 <[hidden email]> wrote:
>
> I too am confused now.  First, I think David <[hidden email]
> <[hidden email]>> 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 <
> [hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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
>>>      [hidden email]             www.ihtfp.com
>>>      Computer and Internet Security Consultant
>>
>> _______________________________________________
>> gnucash-devel mailing list
>> [hidden email]
>> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>>
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

Adrien Monteleone-2
In reply to this post by Geert Janssens-4
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 <[hidden email]> 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&lang=C&doc=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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

Adrien Monteleone-2
In reply to this post by GnuCash - Dev mailing list

> On Aug 21, 2018, at 7:12 AM, David T. <[hidden email]> 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 <mumble-mumble> 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 <[hidden email]> wrote:
>>
>> I too am confused now.  First, I think David <[hidden email]
>> <[hidden email]>> 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 <
>> [hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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
>>>>      [hidden email]             www.ihtfp.com
>>>>      Computer and Internet Security Consultant
>>>
>>> _______________________________________________
>>> gnucash-devel mailing list
>>> [hidden email]
>>> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>>>
>> _______________________________________________
>> gnucash-devel mailing list
>> [hidden email]
>> https://lists.gnucash.org/mailman/listinfo/gnucash-devel


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

John Ralls-2
In reply to this post by Adrien Monteleone-2
Adrien,

If you mean https://help.gnome.org <https://help.gnome.org/>, those docs are built using Yelp tools, see https://gitlab.gnome.org/GNOME?utf8=%E2%9C%93&filter=yelp <https://gitlab.gnome.org/GNOME?utf8=%E2%9C%93&filter=yelp>. Most of that documentation seems pretty cursory, even for largish apps like Gnome Web (aka Epiphany).

Not all “Gnome” projects are included there. The GIMP and Inkscape (though I guess since Inkscape doesn’t keep their repo on gitlab.gnome.org <http://gitlab.gnome.org/> they’re no more a Gnome app than we are), for example, both maintain their own documentation (in DocBook) and doc build scripts.

Gimp’s docs are similar to ours if one doesn’t use viewdoc: They stand apart; there are links to the previous and next pages, there’s a “home” link back to the TOC, but nothing tying it to the main website.

Inkscape doesn’t really have a comprehensive manual. There’s a man page (not on their website) and 9 single-page tutorials (written in DocBook) that are displayed as regular website content pages with no extra links beyond the site menubar across the top.

No doubt that viewdoc.phtml could be improved. As Geert noted it’s pretty basic, just 144 lines of php. If someone fluent in modern php and css would like to overhaul and modernize the website we’d welcome it, but I think the core team’s time is better spent on GnuCash itself.

Regards,
John Ralls

> On Aug 21, 2018, at 8:49 AM, Adrien Monteleone <[hidden email]> wrote:
>
> 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 <[hidden email]> 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&lang=C&doc=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
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

Geert Janssens-4
In reply to this post by Adrien Monteleone-2
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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

John Ralls-2


> On Aug 21, 2018, at 11:50 AM, Geert Janssens <[hidden email]> wrote:
> - it should allow multiple output formats. A few the come to mind:
> html, pdf, epub, mobi, windows compressed help, xml for yelp,...

We don't need a single tool to do that; in fact we don't use a single tool now. We create Windows compressed html (.chm) with HTML Help Workshop from the xslt-created HTML and mobi with calibre from the xslt-created epub.

That aside, I think we should reconsider windows compressed help. Microsoft's own Windows 10 applications seem to open the browser to the relevant documentation page on www.microsoft.com and the help browser is still decorated with Windows 2000 frame and controls. It looks quite jarring. We could more easily just open the documents in a GtkWebkitWebView just like reports.

Regards,
John Ralls


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

John Ralls-2
In reply to this post by Geert Janssens-4


> On Aug 21, 2018, at 11:50 AM, Geert Janssens <[hidden email]> wrote:
>
>
> I believe the gnome project is using Mallard (http://projectmallard.org/).

That depends. The Gnome applications that have help at all use mallard (which is a Docbook dialect) on which they apply yelp-tools and itstool to create documentation. The libraries use gtk-doc to extract specially formatted comments and convert that to a form of Docbook to feed to yelp tools and itstool. In general those documents are published only on the web. The application docs are very simple, no more than a few pages.

> Aside from that they also expect there writers to work with git.

Version control is an obvious hard requirement. I don't know if it completely fulfills your "manageability" requirement, but it's crucial in a collaborative environment to be able to track who-did-what-when and to be able to restore an earlier version if something goes awry.

That said I'm perfectly happy to copy a rewritten section of a document into my working directory and create a commit out of it on behalf of a non-technical author who can't get their head around git.

Regards,
John Ralls

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

Geert Janssens-4
In reply to this post by Geert Janssens-4
Op dinsdag 21 augustus 2018 20:50:38 CEST schreef Geert Janssens:

> Op dinsdag 21 augustus 2018 17:49:57 CEST schreef Adrien Monteleone:
> > 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.
>
Add a way to relatively easily manage translations of the documentation.

Regards,

Geert


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

Geert Janssens-4
In reply to this post by John Ralls-2
Op dinsdag 21 augustus 2018 21:24:25 CEST schreef John Ralls:
> > On Aug 21, 2018, at 11:50 AM, Geert Janssens <[hidden email]>
> > wrote: - it should allow multiple output formats. A few the come to mind:
> > html, pdf, epub, mobi, windows compressed help, xml for yelp,...
>
> We don't need a single tool to do that; in fact we don't use a single tool
> now. We create Windows compressed html (.chm) with HTML Help Workshop from
> the xslt-created HTML and mobi with calibre from the xslt-created epub.
>
It appears while writing down the requirements, I was more considering our
documentation system as a whole, not just a single tool. I agree this can
consist of several tools glued together.

I think what matters is the people actually writing the documentation should
have to learn as few as possible to keep the barrier for contribution very
low. More on that in reply to your other message.

> That aside, I think we should reconsider windows compressed help.
> Microsoft's own Windows 10 applications seem to open the browser to the
> relevant documentation page on www.microsoft.com and the help browser is
> still decorated with Windows 2000 frame and controls. It looks quite
> jarring. We could more easily just open the documents in a GtkWebkitWebView
> just like reports.

I'm all for this. In fact I have proposed this in the past. That also rids us
of one of the more annoying build dependencies on Windows (HtmlHelp).

It would be nice if our html version of the docs would get some css love in
that case though. Wading through plain rendered html is an equally 2000'ish
experience.

Geert


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

Geert Janssens-4
In reply to this post by John Ralls-2
Op dinsdag 21 augustus 2018 21:36:58 CEST schreef John Ralls:
> > On Aug 21, 2018, at 11:50 AM, Geert Janssens <[hidden email]>
> > wrote:
> > Aside from that they also expect there writers to work with git.
>
> Version control is an obvious hard requirement. I don't know if it
> completely fulfills your "manageability" requirement, but it's crucial in a
> collaborative environment to be able to track who-did-what-when and to be
> able to restore an earlier version if something goes awry.
>
In my requirements I deliberately wrote "manageability". Today we use git for
this and from my developer's point of view it has all the features we need. So
I consider it an excellent candidate. Unfortunately most non-developers
experience it as a major hurdle.

So I'm open for alternatives that would equally handle version control, but is
easier for documentation writers to cope with.

This can be a completely different tool that feels more intuitive or it can be
a system layered on top of git which would hide git's technicalities. For
example a web interface that offers online documentation editing and that
behind the scenes stores changes in git. I don't know of such project off-hand
though, but it may be worth looking around for.

Those who need more advanced access can clone the git repo and work locally.


> That said I'm perfectly happy to copy a rewritten section of a document into
> my working directory and create a commit out of it on behalf of a
> non-technical author who can't get their head around git.

Of course. Same for me. Anything that lowers the barrier.

Geert


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

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

Derek Atkins
Geert Janssens <[hidden email]> writes:

[snip]

> So I'm open for alternatives that would equally handle version
> control, but is easier for documentation writers to cope with.
>
> This can be a completely different tool that feels more intuitive or
> it can be a system layered on top of git which would hide git's
> technicalities. For example a web interface that offers online
> documentation editing and that behind the scenes stores changes in
> git. I don't know of such project off-hand though, but it may be worth
> looking around for.
>
> Those who need more advanced access can clone the git repo and work locally.

I wonder how hard it would be to write a web interface on top of git
that abstracts away most of the git work to enable easier access?

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
12