Re: [GNC-dev] Documentation Version Display

[John Ralls]

> On Aug 24, 2018, at 10:35 AM, John Ralls  wrote:
> 
> Good point about the top two links. I’ve modified them to be versioned. I’ll 
> add some clarifying text after I figure out how to not break the translations 
> in the process.

I’ve added a sentence explaining that the top set of links go to the English 
HTML of the current stable version and suggesting that the reader scroll down 
for older versions and different languages and formats.

I’ve msgmerged the new string into the po files to include it.

GENERAL PLEA: Most of the website translations are pretty old and in poor shape:

po/ca.po   418 translated messages, 6 fuzzy translations, 5 untranslated 
messages.
po/de.po   385 translated messages, 3 fuzzy translations, 41 untranslated 
messages.
po/es.po 36 translated messages, 1 fuzzy translation, 392 untranslated 
messages.
po/fr.po264 translated messages, 48 fuzzy translations, 117 
untranslated messages.
po/hu.po   167 translated messages, 63 fuzzy translations, 199 untranslated 
messages.
po/it.po403 translated messages, 15 fuzzy translations, 11 untranslated 
messages.
po/ja.po220 translated messages, 56 fuzzy translations, 153 
untranslated messages.
po/nb.po 66 translated messages, 3 fuzzy translations, 360 untranslated 
messages.
po/nl.po310 translated messages, 31 fuzzy translations, 88 untranslated 
messages.
po/pl.po  72 translated messages, 2 fuzzy translations, 355 
untranslated messages.
po/pt.po403 translated messages, 15 fuzzy translations, 11 untranslated 
messages.
po/zh_CN.po  164 translated messages, 76 fuzzy translations, 189 untranslated 
messages.
po/zh_TW.po  147 translated messages, 22 fuzzy translations, 260 untranslated 
messages.

Anyone able to improve these translations, please jump in !

Regards,
John Ralls

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

Re: [GNC-dev] Documentation Version Display

[Colin Law]

On Sat, 25 Aug 2018 at 15:11, Frank H. Ellenberger
 wrote:
>
> Am 25.08.2018 um 09:39 schrieb Colin Law:
> > On Sat, 25 Aug 2018 at 02:25, David T. via gnucash-devel
> >  wrote:
> >> ...
> >> I imagine most people would search for “gnucash help” or “gnucash 
> >> tutorial.”
> >
> > Actually I think the search is very likely to be something like
> > gnucash how to reconcile account
> > which will take one straight into the middle of the tutorial, hence
> > the need for the version on each page.
>
> No, the recent stable (3.2) is the only version indexed by google. We
> disallow indexing older versions because before the version with most
> links (i.e. 1.x) was listed first.

That does not conflict with what I said, the search will take the user
to the page.  He may not be using the latest version and does not know
that only the latest is indexed, so the page should indicate which
version it is for.

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

Re: [GNC-dev] Documentation Version Display

[Frank H. Ellenberger]

Am 25.08.2018 um 09:39 schrieb Colin Law:
> On Sat, 25 Aug 2018 at 02:25, David T. via gnucash-devel
>  wrote:
>> ...
>> I imagine most people would search for “gnucash help” or “gnucash tutorial.”
> 
> Actually I think the search is very likely to be something like
> gnucash how to reconcile account
> which will take one straight into the middle of the tutorial, hence
> the need for the version on each page. 

No, the recent stable (3.2) is the only version indexed by google. We
disallow indexing older versions because before the version with most
links (i.e. 1.x) was listed first.

 I think new users may well
> search for tutorial or help but once one gets going it is much more
> likely to be a specific search, which may well be quicker than finding
> the tutorial and looking for the right section.
> 
> Colin

Frank

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

Re: [GNC-dev] Documentation Version Display

[Colin Law]

On Sat, 25 Aug 2018 at 02:25, David T. via gnucash-devel
 wrote:
> ...
> I imagine most people would search for “gnucash help” or “gnucash tutorial.”

Actually I think the search is very likely to be something like
gnucash how to reconcile account
which will take one straight into the middle of the tutorial, hence
the need for the version on each page.  I think new users may well
search for tutorial or help but once one gets going it is much more
likely to be a specific search, which may well be quicker than finding
the tutorial and looking for the right section.

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

Re: [GNC-dev] Documentation Version Display

[Colin Law]

Some applications handle this problem by inserting a prominent warning
at the top of each page of out of date documentation, see [1] for
example.  I assume they have some automatic way of doing this rather
than editing all the pages, so whether something like this could be
done without major effort I don't know.

Colin

[1]https://docs.influxdata.com/influxdb/v1.0/introduction/installation/
On Sat, 25 Aug 2018 at 02:25, David T. via gnucash-devel
 wrote:
>
> Adrien,
>
> That seems reasonable, too, although there was recently a long discussion 
> about which online document a user was viewing, suggesting that it’s not 
> always clear.
>
> As for “search juice,” I can’t possibly imagine how there would be a major 
> negative impact by adding “Gnucash v. 3.2” immediately prior the two document 
> titles—and I can’t imagine a search where this would negatively affect 
> results. Honestly, I imagine most people would search for “gnucash help” or 
> “gnucash tutorial.” Such a search presumably would be helped by this change, 
> rather than hurt by it. Not being privy to Google’s search algorithms, I 
> can’t say with authority, or course.
>
> I am opposed to removing these links altogether. As I noted elsewhere, 
> “current stable release” is not IMHO a universally-understood term. And, 
> while I haven’t mentioned it before, I personally find the grid of cryptic 
> icons lined up next to the document titles to be difficult to understand or 
> use. On my screen, they are far too small for me to process visually; of the 
> four in use, I only immediately recognize the PDF icon. The use of a tiny 
> earth icon for HTML help is neither intuitive to me, nor clear to discern. 
> Additionally, I am admittedly unfamiliar with either the Epub or Mobi formats 
> or icons; however, if the goal is to universally communicate the availability 
> of these formats, I don’t think this is the way. But I digress!
>
> The point is, these links clearly put the user into the online documents, 
> which I think is valuable.
>
> David
>
> > On Aug 24, 2018, at 6:30 PM, Adrien Monteleone 
> >  wrote:
> >
> > David,
> >
> > I agree the pages should have both the document title (per another thread) 
> > and the version either in the header or footer.
> >
> > But I can’t fathom clicking the ‘main’ documentation link and thinking that 
> > I’m getting anything other than the most current version. If I knew I was 
> > running an older version of the software and slightly down the page I see a 
> > link for documentation for that version, I’m going to grab that one 
> > instead, making a fairly safe assumption that the main link isn’t for me.
> >
> > The only solution I can think of for this situation is to remove those two 
> > links at the top of the page and users will then click the links for their 
> > chosen version. (with each already well labeled) Adding the version to 
> > those links is, to me, unnecessary clutter. (links should be as concise and 
> > accurately descriptive as possible, and changing that link text each 
> > release will reduce search juice for those links.)
> >
> > Regards,
> > Adrien
> >
> >> On Aug 24, 2018, at 12:03 PM, David T. via gnucash-devel 
> >>  wrote:
> >>
> >> John,
> >>
> >>
> >>> On Aug 24, 2018, at 10:57 AM, John Ralls  wrote:
> >>>
> >>>
> >>>
>  On Aug 24, 2018, at 5:51 AM, David T. via gnucash-devel 
>   wrote:
> 
>  Hello,
> 
>  Today, I had the opportunity to examine the online Help text, where I 
>  saw detailed information about the Transaction Report, which has 
>  recently changed radically. The information provided on the online Help 
>  clearly references the new version of this report, which I surmise 
>  because I am still running 2.6.21, and I do not have this version of the 
>  report.
> 
>  Here is the problem: there is no indication in the online resources 
>  (either in the document itself, or on Gnucash.org ) 
>  the version of GnuCash to which the documentation refers. This could 
>  lead to user confusion, as they see help that refers to functionality 
>  that they do not have.
> 
>  I am sure that the stock answer here will be: “GnuCash is currently on 
>  release 3.2, and therefore the documentation available at Gnucash.org 
>   reflects the current release.” I respect that.
> 
>  However, at any given time, there will be people who choose for one 
>  reason or another not to upgrade to the latest and greatest version—or 
>  more problematically, are unaware that they are not running the latest 
>  version. These users would benefit from being informed *somewhere* that 
>  the documentation that they are consulting is for a particular version. 
>  Is there some way to add the version number to the header of the 
>  documentation pages? (The footer is also an option, but is less 
>  preferable online since the footer 

Re: [GNC-dev] Documentation Version Display

[David T. via gnucash-devel]

Adrien,

That seems reasonable, too, although there was recently a long discussion about 
which online document a user was viewing, suggesting that it’s not always clear.

As for “search juice,” I can’t possibly imagine how there would be a major 
negative impact by adding “Gnucash v. 3.2” immediately prior the two document 
titles—and I can’t imagine a search where this would negatively affect results. 
Honestly, I imagine most people would search for “gnucash help” or “gnucash 
tutorial.” Such a search presumably would be helped by this change, rather than 
hurt by it. Not being privy to Google’s search algorithms, I can’t say with 
authority, or course.

I am opposed to removing these links altogether. As I noted elsewhere, “current 
stable release” is not IMHO a universally-understood term. And, while I haven’t 
mentioned it before, I personally find the grid of cryptic icons lined up next 
to the document titles to be difficult to understand or use. On my screen, they 
are far too small for me to process visually; of the four in use, I only 
immediately recognize the PDF icon. The use of a tiny earth icon for HTML help 
is neither intuitive to me, nor clear to discern. Additionally, I am admittedly 
unfamiliar with either the Epub or Mobi formats or icons; however, if the goal 
is to universally communicate the availability of these formats, I don’t think 
this is the way. But I digress! 

The point is, these links clearly put the user into the online documents, which 
I think is valuable.

David

> On Aug 24, 2018, at 6:30 PM, Adrien Monteleone 
>  wrote:
> 
> David,
> 
> I agree the pages should have both the document title (per another thread) 
> and the version either in the header or footer.
> 
> But I can’t fathom clicking the ‘main’ documentation link and thinking that 
> I’m getting anything other than the most current version. If I knew I was 
> running an older version of the software and slightly down the page I see a 
> link for documentation for that version, I’m going to grab that one instead, 
> making a fairly safe assumption that the main link isn’t for me.
> 
> The only solution I can think of for this situation is to remove those two 
> links at the top of the page and users will then click the links for their 
> chosen version. (with each already well labeled) Adding the version to those 
> links is, to me, unnecessary clutter. (links should be as concise and 
> accurately descriptive as possible, and changing that link text each release 
> will reduce search juice for those links.)
> 
> Regards,
> Adrien
> 
>> On Aug 24, 2018, at 12:03 PM, David T. via gnucash-devel 
>>  wrote:
>> 
>> John, 
>> 
>> 
>>> On Aug 24, 2018, at 10:57 AM, John Ralls  wrote:
>>> 
>>> 
>>> 
 On Aug 24, 2018, at 5:51 AM, David T. via gnucash-devel 
  wrote:
 
 Hello,
 
 Today, I had the opportunity to examine the online Help text, where I saw 
 detailed information about the Transaction Report, which has recently 
 changed radically. The information provided on the online Help clearly 
 references the new version of this report, which I surmise because I am 
 still running 2.6.21, and I do not have this version of the report.
 
 Here is the problem: there is no indication in the online resources 
 (either in the document itself, or on Gnucash.org ) 
 the version of GnuCash to which the documentation refers. This could lead 
 to user confusion, as they see help that refers to functionality that they 
 do not have.
 
 I am sure that the stock answer here will be: “GnuCash is currently on 
 release 3.2, and therefore the documentation available at Gnucash.org 
  reflects the current release.” I respect that. 
 
 However, at any given time, there will be people who choose for one reason 
 or another not to upgrade to the latest and greatest version—or more 
 problematically, are unaware that they are not running the latest version. 
 These users would benefit from being informed *somewhere* that the 
 documentation that they are consulting is for a particular version. Is 
 there some way to add the version number to the header of the 
 documentation pages? (The footer is also an option, but is less preferable 
 online since the footer is often well off screen, and may not be noticed 
 by a distressed user trying to figure out a problem). If the version 
 covered were presented on screen on every page, then the user would have a 
 clear reminder of this.
>>> 
>>> David,
>>> 
>>> Sure there is.
>>> 
>>> On https://www.gnucash.org/docs.phtml there’s a huge header above each set 
>>> of document links: "GnuCash v3 (current stable release)”, “GnuCash v2.6 
>>> (old stable release)”,
>>> “Nightly Documentation Builds”, and “Older GnuCash Documentation”.
>> 
>> You overlook the large section above this which prominently proclaims the 
>> "two major 

Re: [GNC-dev] Documentation Version Display

[Adrien Monteleone]

David,

I agree the pages should have both the document title (per another thread) and 
the version either in the header or footer.

But I can’t fathom clicking the ‘main’ documentation link and thinking that I’m 
getting anything other than the most current version. If I knew I was running 
an older version of the software and slightly down the page I see a link for 
documentation for that version, I’m going to grab that one instead, making a 
fairly safe assumption that the main link isn’t for me.

The only solution I can think of for this situation is to remove those two 
links at the top of the page and users will then click the links for their 
chosen version. (with each already well labeled) Adding the version to those 
links is, to me, unnecessary clutter. (links should be as concise and 
accurately descriptive as possible, and changing that link text each release 
will reduce search juice for those links.)

Regards,
Adrien

> On Aug 24, 2018, at 12:03 PM, David T. via gnucash-devel 
>  wrote:
> 
> John, 
> 
> 
>> On Aug 24, 2018, at 10:57 AM, John Ralls  wrote:
>> 
>> 
>> 
>>> On Aug 24, 2018, at 5:51 AM, David T. via gnucash-devel 
>>>  wrote:
>>> 
>>> Hello,
>>> 
>>> Today, I had the opportunity to examine the online Help text, where I saw 
>>> detailed information about the Transaction Report, which has recently 
>>> changed radically. The information provided on the online Help clearly 
>>> references the new version of this report, which I surmise because I am 
>>> still running 2.6.21, and I do not have this version of the report.
>>> 
>>> Here is the problem: there is no indication in the online resources (either 
>>> in the document itself, or on Gnucash.org ) the 
>>> version of GnuCash to which the documentation refers. This could lead to 
>>> user confusion, as they see help that refers to functionality that they do 
>>> not have.
>>> 
>>> I am sure that the stock answer here will be: “GnuCash is currently on 
>>> release 3.2, and therefore the documentation available at Gnucash.org 
>>>  reflects the current release.” I respect that. 
>>> 
>>> However, at any given time, there will be people who choose for one reason 
>>> or another not to upgrade to the latest and greatest version—or more 
>>> problematically, are unaware that they are not running the latest version. 
>>> These users would benefit from being informed *somewhere* that the 
>>> documentation that they are consulting is for a particular version. Is 
>>> there some way to add the version number to the header of the documentation 
>>> pages? (The footer is also an option, but is less preferable online since 
>>> the footer is often well off screen, and may not be noticed by a distressed 
>>> user trying to figure out a problem). If the version covered were presented 
>>> on screen on every page, then the user would have a clear reminder of this.
>> 
>> David,
>> 
>> Sure there is.
>> 
>> On https://www.gnucash.org/docs.phtml there’s a huge header above each set 
>> of document links: "GnuCash v3 (current stable release)”, “GnuCash v2.6 (old 
>> stable release)”,
>> “Nightly Documentation Builds”, and “Older GnuCash Documentation”.
> 
> You overlook the large section above this which prominently proclaims the 
> "two major GnuCash documentation packages” and provides direct links to each 
> of these ***without making any statement of version***. Moreover, the 
> structure of the page would imply that the documents behind *these* links are 
> somehow different from the ones beneath the "current stable release” header. 
> Perhaps the ones at the top are newer and better? It’s difficult to tell. 
> I’ll note that the links behind these entries even differ, making it 
> practically speaking impossible for a user to know whether these two 
> documents are in fact the same. I would finally suggest that “current stable 
> release” is not as universal a term as many in this community think it is. I 
> believe that many users wouldn’t know what it signifies.
> 
> 
>> 
>> Once you’re browsing the document, go to “About this Document” from the 
>> table of contents. After “Legal Notice” and “Feedback” you’ll find 
>> “History”, the top entry of which indicates the exact release for which the 
>> documentation applies.
> 
> The About this document appears only on the main TOC page. What about the 
> rest of the document? Users don’t always access our online help via the main 
> TOC.
> 
>> 
>> Of course it’s possible to add the version into the header. I suppose the 
>> simplest would be to change the chapter titles e.g. “Chapter 4. GnuCash 
>> Windows & Menus Overview” to “Chapter 4. GnuCash v3.2  Windows & Menus 
>> Overview”, just change the chapter title from 
>>  Windows  Menus Overview
>> to
>>   Windows  Menus Overview
>> Chapter titles (“Getting Started”) that don’t include the application tag 
>> would need to be reworded, e.g. “Getting Started with GnuCash 3.2”.
> 
> How hard would it 

Re: [GNC-dev] Documentation Version Display

[D via gnucash-devel]

On August 24, 2018, at 2:11 PM, John Ralls  wrote:

>
>
>On Aug 24, 2018, at 10:49 AM, David T.  wrote:
>
>On Aug 24, 2018, at 1:35 PM, John Ralls  wrote:
>
>On Aug 24, 2018, at 10:03 AM, David T.  wrote:
>
>John, 
>On Aug 24, 2018, at 10:57 AM, John Ralls  wrote:
>On Aug 24, 2018, at 5:51 AM, David T. via gnucash-devel 
> wrote:
>Hello,
>Today, I had the opportunity to examine the online Help text, where I saw 
>detailed information about the Transaction Report, which has recently changed 
>radically. The information provided on the online Help clearly references the 
>new version of this report, which I surmise because I am still running 2.6.21, 
>and I do not have this version of the report.
>Here is the problem: there is no indication in the online resources (either in 
>the document itself, or on Gnucash.org ) the version of 
>GnuCash to which the documentation refers. This could lead to user confusion, 
>as they see help that refers to functionality that they do not have.
>I am sure that the stock answer here will be: “GnuCash is currently on release 
>3.2, and therefore the documentation available at Gnucash.org 
> reflects the current release.” I respect that. 
>However, at any given time, there will be people who choose for one reason or 
>another not to upgrade to the latest and greatest version—or more 
>problematically, are unaware that they are not running the latest version. 
>These users would benefit from being informed *somewhere* that the 
>documentation that they are consulting is for a particular version. Is there 
>some way to add the version number to the header of the documentation pages? 
>(The footer is also an option, but is less preferable online since the footer 
>is often well off screen, and may not be noticed by a distressed user trying 
>to figure out a problem). If the version covered were presented on screen on 
>every page, then the user would have a clear reminder of this.
>David,
>Sure there is.
>On https://www.gnucash.org/docs.phtml there’s a huge header above each set of 
>document links: "GnuCash v3 (current stable release)”, “GnuCash v2.6 (old 
>stable release)”,
>“Nightly Documentation Builds”, and “Older GnuCash Documentation”.
>You overlook the large section above this which prominently proclaims the "two 
>major GnuCash documentation packages” and provides direct links to each of 
>these ***without making any statement of version***. Moreover, the structure 
>of the page would imply that the documents behind *these* links are somehow 
>different from the ones beneath the "current stable release” header. Perhaps 
>the ones at the top are newer and better? It’s difficult to tell. I’ll note 
>that the links behind these entries even differ, making it practically 
>speaking impossible for a user to know whether these two documents are in fact 
>the same. I would finally suggest that “current stable release” is not as 
>universal a term as many in this community think it is. I believe that many 
>users wouldn’t know what it signifies.
>Once you’re browsing the document, go to “About this Document” from the table 
>of contents. After “Legal Notice” and “Feedback” you’ll find “History”, the 
>top entry of which indicates the exact release for which the documentation 
>applies.
>The About this document appears only on the main TOC page. What about the rest 
>of the document? Users don’t always access our online help via the main TOC.
>Of course it’s possible to add the version into the header. I suppose the 
>simplest would be to change the chapter titles e.g. “Chapter 4. GnuCash 
>Windows & Menus Overview” to “Chapter 4. GnuCash v3.2  Windows & Menus 
>Overview”, just change the chapter title from 
> Windows  Menus Overview
>to
>  Windows  Menus Overview
>Chapter titles (“Getting Started”) that don’t include the application tag 
>would need to be reworded, e.g. “Getting Started with GnuCash 3.2”.
>How hard would it be to have each header get a second line with  
>programmatically added during the generation process?
>Chapter 4. GnuCash Windows & Menus Overview
>v3.2
>
>David,
>
>Good point about the top two links. I’ve modified them to be versioned. I’ll 
>add some clarifying text after I figure out how to not break the translations 
>in the process.
>
>The header line would be a third in most cases, the first being the section, 
>see e.g. https://www.gnucash.org/docs/v3/C/gnucash-help/acct-create.html. I 
>think that would be pretty ugly. Note that in light of your objection that 
>users don’t always access the online help via the main ToC that there are also 
>mid-page anchors; users going there (often via context help) won’t see either 
>the header or the footer. OTOH unless the packager has screwed up, the help 
>accessed via context help should be the version associated with the GnuCash 
>version being used.
>
>Regards,
>
>John Ralls
>
>John,
>
>I see your point about adding Yet Another Line to the header. What about 

Re: [GNC-dev] Documentation Version Display

[John Ralls]

> On Aug 24, 2018, at 10:49 AM, David T.  wrote:
> 
> 
> 
>> On Aug 24, 2018, at 1:35 PM, John Ralls > > wrote:
>> 
>> 
>> 
>>> On Aug 24, 2018, at 10:03 AM, David T. >> > wrote:
>>> 
>>> John, 
>>> 
>>> 
 On Aug 24, 2018, at 10:57 AM, John Ralls >>> > wrote:
 
 
 
> On Aug 24, 2018, at 5:51 AM, David T. via gnucash-devel 
> mailto:gnucash-devel@gnucash.org>> wrote:
> 
> Hello,
> 
> Today, I had the opportunity to examine the online Help text, where I saw 
> detailed information about the Transaction Report, which has recently 
> changed radically. The information provided on the online Help clearly 
> references the new version of this report, which I surmise because I am 
> still running 2.6.21, and I do not have this version of the report.
> 
> Here is the problem: there is no indication in the online resources 
> (either in the document itself, or on Gnucash.org  
> >) the version of GnuCash to 
> which the documentation refers. This could lead to user confusion, as 
> they see help that refers to functionality that they do not have.
> 
> I am sure that the stock answer here will be: “GnuCash is currently on 
> release 3.2, and therefore the documentation available at Gnucash.org 
>  > 
> reflects the current release.” I respect that. 
> 
> However, at any given time, there will be people who choose for one 
> reason or another not to upgrade to the latest and greatest version—or 
> more problematically, are unaware that they are not running the latest 
> version. These users would benefit from being informed *somewhere* that 
> the documentation that they are consulting is for a particular version. 
> Is there some way to add the version number to the header of the 
> documentation pages? (The footer is also an option, but is less 
> preferable online since the footer is often well off screen, and may not 
> be noticed by a distressed user trying to figure out a problem). If the 
> version covered were presented on screen on every page, then the user 
> would have a clear reminder of this.
 
 David,
 
 Sure there is.
 
 On https://www.gnucash.org/docs.phtml  
 there’s a huge header above each set of document links: "GnuCash v3 
 (current stable release)”, “GnuCash v2.6 (old stable release)”,
 “Nightly Documentation Builds”, and “Older GnuCash Documentation”.
>>> 
>>> You overlook the large section above this which prominently proclaims the 
>>> "two major GnuCash documentation packages” and provides direct links to 
>>> each of these ***without making any statement of version***. Moreover, the 
>>> structure of the page would imply that the documents behind *these* links 
>>> are somehow different from the ones beneath the "current stable release” 
>>> header. Perhaps the ones at the top are newer and better? It’s difficult to 
>>> tell. I’ll note that the links behind these entries even differ, making it 
>>> practically speaking impossible for a user to know whether these two 
>>> documents are in fact the same. I would finally suggest that “current 
>>> stable release” is not as universal a term as many in this community think 
>>> it is. I believe that many users wouldn’t know what it signifies.
>>> 
>>> 
 
 Once you’re browsing the document, go to “About this Document” from the 
 table of contents. After “Legal Notice” and “Feedback” you’ll find 
 “History”, the top entry of which indicates the exact release for which 
 the documentation applies.
>>> 
>>> The About this document appears only on the main TOC page. What about the 
>>> rest of the document? Users don’t always access our online help via the 
>>> main TOC.
>>> 
 
 Of course it’s possible to add the version into the header. I suppose the 
 simplest would be to change the chapter titles e.g. “Chapter 4. GnuCash 
 Windows & Menus Overview” to “Chapter 4. GnuCash v3.2  Windows & Menus 
 Overview”, just change the chapter title from 
  Windows  Menus Overview
 to
   Windows  Menus Overview
 Chapter titles (“Getting Started”) that don’t include the application tag 
 would need to be reworded, e.g. “Getting Started with GnuCash 3.2”.
>>> 
>>> How hard would it be to have each header get a second line with 
>>>  programmatically added during the generation process?
>>> 
>>> Chapter 4. GnuCash Windows & Menus Overview
>>> v3.2
>> 
>> David,
>> 
>> Good point about the top two links. I’ve modified them to be versioned. I’ll 
>> add some clarifying text after I figure out how to not break the 
>> translations in the process.
>> 
>> The header line would be a third 

Re: [GNC-dev] Documentation Version Display

[David T. via gnucash-devel]

> On Aug 24, 2018, at 1:35 PM, John Ralls  wrote:
> 
> 
> 
>> On Aug 24, 2018, at 10:03 AM, David T. > > wrote:
>> 
>> John, 
>> 
>> 
>>> On Aug 24, 2018, at 10:57 AM, John Ralls >> > wrote:
>>> 
>>> 
>>> 
 On Aug 24, 2018, at 5:51 AM, David T. via gnucash-devel 
 mailto:gnucash-devel@gnucash.org>> wrote:
 
 Hello,
 
 Today, I had the opportunity to examine the online Help text, where I saw 
 detailed information about the Transaction Report, which has recently 
 changed radically. The information provided on the online Help clearly 
 references the new version of this report, which I surmise because I am 
 still running 2.6.21, and I do not have this version of the report.
 
 Here is the problem: there is no indication in the online resources 
 (either in the document itself, or on Gnucash.org  
 >) the version of GnuCash to 
 which the documentation refers. This could lead to user confusion, as they 
 see help that refers to functionality that they do not have.
 
 I am sure that the stock answer here will be: “GnuCash is currently on 
 release 3.2, and therefore the documentation available at Gnucash.org 
  > reflects 
 the current release.” I respect that. 
 
 However, at any given time, there will be people who choose for one reason 
 or another not to upgrade to the latest and greatest version—or more 
 problematically, are unaware that they are not running the latest version. 
 These users would benefit from being informed *somewhere* that the 
 documentation that they are consulting is for a particular version. Is 
 there some way to add the version number to the header of the 
 documentation pages? (The footer is also an option, but is less preferable 
 online since the footer is often well off screen, and may not be noticed 
 by a distressed user trying to figure out a problem). If the version 
 covered were presented on screen on every page, then the user would have a 
 clear reminder of this.
>>> 
>>> David,
>>> 
>>> Sure there is.
>>> 
>>> On https://www.gnucash.org/docs.phtml  
>>> there’s a huge header above each set of document links: "GnuCash v3 
>>> (current stable release)”, “GnuCash v2.6 (old stable release)”,
>>> “Nightly Documentation Builds”, and “Older GnuCash Documentation”.
>> 
>> You overlook the large section above this which prominently proclaims the 
>> "two major GnuCash documentation packages” and provides direct links to each 
>> of these ***without making any statement of version***. Moreover, the 
>> structure of the page would imply that the documents behind *these* links 
>> are somehow different from the ones beneath the "current stable release” 
>> header. Perhaps the ones at the top are newer and better? It’s difficult to 
>> tell. I’ll note that the links behind these entries even differ, making it 
>> practically speaking impossible for a user to know whether these two 
>> documents are in fact the same. I would finally suggest that “current stable 
>> release” is not as universal a term as many in this community think it is. I 
>> believe that many users wouldn’t know what it signifies.
>> 
>> 
>>> 
>>> Once you’re browsing the document, go to “About this Document” from the 
>>> table of contents. After “Legal Notice” and “Feedback” you’ll find 
>>> “History”, the top entry of which indicates the exact release for which the 
>>> documentation applies.
>> 
>> The About this document appears only on the main TOC page. What about the 
>> rest of the document? Users don’t always access our online help via the main 
>> TOC.
>> 
>>> 
>>> Of course it’s possible to add the version into the header. I suppose the 
>>> simplest would be to change the chapter titles e.g. “Chapter 4. GnuCash 
>>> Windows & Menus Overview” to “Chapter 4. GnuCash v3.2  Windows & Menus 
>>> Overview”, just change the chapter title from 
>>>  Windows  Menus Overview
>>> to
>>>   Windows  Menus Overview
>>> Chapter titles (“Getting Started”) that don’t include the application tag 
>>> would need to be reworded, e.g. “Getting Started with GnuCash 3.2”.
>> 
>> How hard would it be to have each header get a second line with  
>> programmatically added during the generation process?
>> 
>> Chapter 4. GnuCash Windows & Menus Overview
>> v3.2
> 
> David,
> 
> Good point about the top two links. I’ve modified them to be versioned. I’ll 
> add some clarifying text after I figure out how to not break the translations 
> in the process.
> 
> The header line would be a third in most cases, the first being the section, 
> see e.g. https://www.gnucash.org/docs/v3/C/gnucash-help/acct-create.html 
> . I 

Re: [GNC-dev] Documentation Version Display

[John Ralls]

> On Aug 24, 2018, at 10:03 AM, David T.  wrote:
> 
> John, 
> 
> 
>> On Aug 24, 2018, at 10:57 AM, John Ralls  wrote:
>> 
>> 
>> 
>>> On Aug 24, 2018, at 5:51 AM, David T. via gnucash-devel 
>>>  wrote:
>>> 
>>> Hello,
>>> 
>>> Today, I had the opportunity to examine the online Help text, where I saw 
>>> detailed information about the Transaction Report, which has recently 
>>> changed radically. The information provided on the online Help clearly 
>>> references the new version of this report, which I surmise because I am 
>>> still running 2.6.21, and I do not have this version of the report.
>>> 
>>> Here is the problem: there is no indication in the online resources (either 
>>> in the document itself, or on Gnucash.org ) the 
>>> version of GnuCash to which the documentation refers. This could lead to 
>>> user confusion, as they see help that refers to functionality that they do 
>>> not have.
>>> 
>>> I am sure that the stock answer here will be: “GnuCash is currently on 
>>> release 3.2, and therefore the documentation available at Gnucash.org 
>>>  reflects the current release.” I respect that. 
>>> 
>>> However, at any given time, there will be people who choose for one reason 
>>> or another not to upgrade to the latest and greatest version—or more 
>>> problematically, are unaware that they are not running the latest version. 
>>> These users would benefit from being informed *somewhere* that the 
>>> documentation that they are consulting is for a particular version. Is 
>>> there some way to add the version number to the header of the documentation 
>>> pages? (The footer is also an option, but is less preferable online since 
>>> the footer is often well off screen, and may not be noticed by a distressed 
>>> user trying to figure out a problem). If the version covered were presented 
>>> on screen on every page, then the user would have a clear reminder of this.
>> 
>> David,
>> 
>> Sure there is.
>> 
>> On https://www.gnucash.org/docs.phtml there’s a huge header above each set 
>> of document links: "GnuCash v3 (current stable release)”, “GnuCash v2.6 (old 
>> stable release)”,
>> “Nightly Documentation Builds”, and “Older GnuCash Documentation”.
> 
> You overlook the large section above this which prominently proclaims the 
> "two major GnuCash documentation packages” and provides direct links to each 
> of these ***without making any statement of version***. Moreover, the 
> structure of the page would imply that the documents behind *these* links are 
> somehow different from the ones beneath the "current stable release” header. 
> Perhaps the ones at the top are newer and better? It’s difficult to tell. 
> I’ll note that the links behind these entries even differ, making it 
> practically speaking impossible for a user to know whether these two 
> documents are in fact the same. I would finally suggest that “current stable 
> release” is not as universal a term as many in this community think it is. I 
> believe that many users wouldn’t know what it signifies.
> 
> 
>> 
>> Once you’re browsing the document, go to “About this Document” from the 
>> table of contents. After “Legal Notice” and “Feedback” you’ll find 
>> “History”, the top entry of which indicates the exact release for which the 
>> documentation applies.
> 
> The About this document appears only on the main TOC page. What about the 
> rest of the document? Users don’t always access our online help via the main 
> TOC.
> 
>> 
>> Of course it’s possible to add the version into the header. I suppose the 
>> simplest would be to change the chapter titles e.g. “Chapter 4. GnuCash 
>> Windows & Menus Overview” to “Chapter 4. GnuCash v3.2  Windows & Menus 
>> Overview”, just change the chapter title from 
>>  Windows  Menus Overview
>> to
>>   Windows  Menus Overview
>> Chapter titles (“Getting Started”) that don’t include the application tag 
>> would need to be reworded, e.g. “Getting Started with GnuCash 3.2”.
> 
> How hard would it be to have each header get a second line with  
> programmatically added during the generation process?
> 
> Chapter 4. GnuCash Windows & Menus Overview
> v3.2

David,

Good point about the top two links. I’ve modified them to be versioned. I’ll 
add some clarifying text after I figure out how to not break the translations 
in the process.

The header line would be a third in most cases, the first being the section, 
see e.g. https://www.gnucash.org/docs/v3/C/gnucash-help/acct-create.html. I 
think that would be pretty ugly. Note that in light of your objection that 
users don’t always access the online help via the main ToC that there are also 
mid-page anchors; users going there (often via context help) won’t see either 
the header or the footer. OTOH unless the packager has screwed up, the help 
accessed via context help should be the version associated with the GnuCash 
version being used.

Regards,
John Ralls

Re: [GNC-dev] Documentation Version Display

[Adrien Monteleone]

Without cluttering up titles and chapter names, utilizing the footer of each 
page to include the version number would work as well.

Regards,
Adrien

> On Aug 24, 2018, at 9:57 AM, John Ralls  wrote:
> 
> 
> 
>> On Aug 24, 2018, at 5:51 AM, David T. via gnucash-devel 
>>  wrote:
>> 
>> Hello,
>> 
>> Today, I had the opportunity to examine the online Help text, where I saw 
>> detailed information about the Transaction Report, which has recently 
>> changed radically. The information provided on the online Help clearly 
>> references the new version of this report, which I surmise because I am 
>> still running 2.6.21, and I do not have this version of the report.
>> 
>> Here is the problem: there is no indication in the online resources (either 
>> in the document itself, or on Gnucash.org ) the version 
>> of GnuCash to which the documentation refers. This could lead to user 
>> confusion, as they see help that refers to functionality that they do not 
>> have.
>> 
>> I am sure that the stock answer here will be: “GnuCash is currently on 
>> release 3.2, and therefore the documentation available at Gnucash.org 
>>  reflects the current release.” I respect that. 
>> 
>> However, at any given time, there will be people who choose for one reason 
>> or another not to upgrade to the latest and greatest version—or more 
>> problematically, are unaware that they are not running the latest version. 
>> These users would benefit from being informed *somewhere* that the 
>> documentation that they are consulting is for a particular version. Is there 
>> some way to add the version number to the header of the documentation pages? 
>> (The footer is also an option, but is less preferable online since the 
>> footer is often well off screen, and may not be noticed by a distressed user 
>> trying to figure out a problem). If the version covered were presented on 
>> screen on every page, then the user would have a clear reminder of this.
> 
> David,
> 
> Sure there is.
> 
> On https://www.gnucash.org/docs.phtml there’s a huge header above each set of 
> document links: "GnuCash v3 (current stable release)”, “GnuCash v2.6 (old 
> stable release)”,
> “Nightly Documentation Builds”, and “Older GnuCash Documentation”.
> 
> Once you’re browsing the document, go to “About this Document” from the table 
> of contents. After “Legal Notice” and “Feedback” you’ll find “History”, the 
> top entry of which indicates the exact release for which the documentation 
> applies.
> 
> Of course it’s possible to add the version into the header. I suppose the 
> simplest would be to change the chapter titles e.g. “Chapter 4. GnuCash 
> Windows & Menus Overview” to “Chapter 4. GnuCash v3.2  Windows & Menus 
> Overview”, just change the chapter title from 
>  Windows  Menus Overview
> to
>   Windows  Menus Overview
>  Chapter titles (“Getting Started”) that don’t include the application tag 
> would need to be reworded, e.g. “Getting Started with GnuCash 3.2”.
> 
> Regards,
> John Ralls
> 
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel


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

Re: [GNC-dev] Documentation Version Display

[John Ralls]

> On Aug 24, 2018, at 5:51 AM, David T. via gnucash-devel 
>  wrote:
> 
> Hello,
> 
> Today, I had the opportunity to examine the online Help text, where I saw 
> detailed information about the Transaction Report, which has recently changed 
> radically. The information provided on the online Help clearly references the 
> new version of this report, which I surmise because I am still running 
> 2.6.21, and I do not have this version of the report.
> 
> Here is the problem: there is no indication in the online resources (either 
> in the document itself, or on Gnucash.org ) the version 
> of GnuCash to which the documentation refers. This could lead to user 
> confusion, as they see help that refers to functionality that they do not 
> have.
> 
> I am sure that the stock answer here will be: “GnuCash is currently on 
> release 3.2, and therefore the documentation available at Gnucash.org 
>  reflects the current release.” I respect that. 
> 
> However, at any given time, there will be people who choose for one reason or 
> another not to upgrade to the latest and greatest version—or more 
> problematically, are unaware that they are not running the latest version. 
> These users would benefit from being informed *somewhere* that the 
> documentation that they are consulting is for a particular version. Is there 
> some way to add the version number to the header of the documentation pages? 
> (The footer is also an option, but is less preferable online since the footer 
> is often well off screen, and may not be noticed by a distressed user trying 
> to figure out a problem). If the version covered were presented on screen on 
> every page, then the user would have a clear reminder of this.

David,

Sure there is.

 On https://www.gnucash.org/docs.phtml there’s a huge header above each set of 
document links: "GnuCash v3 (current stable release)”, “GnuCash v2.6 (old 
stable release)”,
“Nightly Documentation Builds”, and “Older GnuCash Documentation”.

Once you’re browsing the document, go to “About this Document” from the table 
of contents. After “Legal Notice” and “Feedback” you’ll find “History”, the top 
entry of which indicates the exact release for which the documentation applies.

Of course it’s possible to add the version into the header. I suppose the 
simplest would be to change the chapter titles e.g. “Chapter 4. GnuCash Windows 
& Menus Overview” to “Chapter 4. GnuCash v3.2  Windows & Menus Overview”, just 
change the chapter title from 
 Windows  Menus Overview
to
  Windows  Menus Overview
  Chapter titles (“Getting Started”) that don’t include the application tag 
would need to be reworded, e.g. “Getting Started with GnuCash 3.2”.

Regards,
John Ralls

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

[GNC-dev] Documentation Version Display

[David T. via gnucash-devel]

Hello,

Today, I had the opportunity to examine the online Help text, where I saw 
detailed information about the Transaction Report, which has recently changed 
radically. The information provided on the online Help clearly references the 
new version of this report, which I surmise because I am still running 2.6.21, 
and I do not have this version of the report.

Here is the problem: there is no indication in the online resources (either in 
the document itself, or on Gnucash.org ) the version of 
GnuCash to which the documentation refers. This could lead to user confusion, 
as they see help that refers to functionality that they do not have.

I am sure that the stock answer here will be: “GnuCash is currently on release 
3.2, and therefore the documentation available at Gnucash.org 
 reflects the current release.” I respect that. 

However, at any given time, there will be people who choose for one reason or 
another not to upgrade to the latest and greatest version—or more 
problematically, are unaware that they are not running the latest version. 
These users would benefit from being informed *somewhere* that the 
documentation that they are consulting is for a particular version. Is there 
some way to add the version number to the header of the documentation pages? 
(The footer is also an option, but is less preferable online since the footer 
is often well off screen, and may not be noticed by a distressed user trying to 
figure out a problem). If the version covered were presented on screen on every 
page, then the user would have a clear reminder of this.

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