[GNC-dev] Documentation Version Display

Sat Aug 25 03:27:17 EDT 2018

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
<gnucash-devel at gnucash.org> 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 <adrien.monteleone at lusfiber.net> 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 <gnucash-devel at gnucash.org> wrote:
> >>
> >> John,
> >>
> >>
> >>> On Aug 24, 2018, at 10:57 AM, John Ralls <jralls at ceridwen.us> wrote:
> >>>
> >>>
> >>>
> >>>> On Aug 24, 2018, at 5:51 AM, David T. via gnucash-devel <gnucash-devel at 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 <http://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 <http://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
> >>> <application>&app;</application> Windows & Menus Overview
> >>> to
> >>> <application>&app; &vers-stable;</application> 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 &vers-stable programmatically added during the generation process?
> >>
> >> Chapter 4. GnuCash Windows & Menus Overview
> >> v3.2
> >>
> >> David
> >>
> >>>
> >>> Regards,
> >>> John Ralls
> >>>
> >>
> >> _______________________________________________
> >> gnucash-devel mailing list
> >> gnucash-devel at gnucash.org
> >> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> >
> >
> > _______________________________________________
> > gnucash-devel mailing list
> > gnucash-devel at gnucash.org
> > https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel