Re: [GNC-dev] Long Term Documentation Directions
John, Point taken. I rarely use the yelp viewer from inside Gnucash at all and mainly use the online HTML documentation. It could be to separate context sensitive help into it's own structureis one way to go. I would have thought for the more tutorial aspects currently in the guide it would also be useful to link to widget specific information e.g. a reference to a specific button as a link to the button description and not have to include what the button does. . I think the current documentation processing for docbook xml takes care of that by editing out features that are not supported in a particular format using the xsl files or converting to the appropriate format. PDF and HTML both have the capacity to construct internal and external links. https://helpx.adobe.com/acrobat/kb/link-html-pdf-page-acrobat.html suggests it is possible to link to specific points in a pdf. I think Geert's point about someone imposing quality control and some sort of editorial policy is quite valid. David Cousens - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
> On Sep 11, 2018, at 5:12 PM, David Cousens wrote: > > Hi John, > > I do understand that alternatives to docbook are being considered. > > I keep referring to it primarily because it is the current format, rather > than necessarily the best or even what may be used in future. Perhaps with > an assumption that whatever format is decided on, it will at least have the > same conversion capabilities and the ability to construct an automated build > workflow as are present in the current documentation tool chain. > > Also as a way of arguing for not embedding context sensitive help in hard > code if it is avoidable. I do take the point though that such information > does only change slowly if at all so I think a separate file perhaps with a > more restricted editing access could be a way to handle that. > > The availability of some good open source free wsiwyg editors for markdown > would certainly help documenters with a less technical background and > pandoc seems to be capable of building into a toolchain for converion for > example. I haven't found out yet whether it uses some form of xls to control > the conversion which is customizable. David, That misses the point a bit, which is that regardless of what format we keep the sources in the documents that users read will mostly be some form of HTML or PDF and we're limited to the feature set that those markup languages provide. For the current discussion that particularly applies with respect to cross-document links. Regards, John Ralls ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
Hi John, I do understand that alternatives to docbook are being considered. I keep referring to it primarily because it is the current format, rather than necessarily the best or even what may be used in future. Perhaps with an assumption that whatever format is decided on, it will at least have the same conversion capabilities and the ability to construct an automated build workflow as are present in the current documentation tool chain. Also as a way of arguing for not embedding context sensitive help in hard code if it is avoidable. I do take the point though that such information does only change slowly if at all so I think a separate file perhaps with a more restricted editing access could be a way to handle that. The availability of some good open source free wsiwyg editors for markdown would certainly help documenters with a less technical background and pandoc seems to be capable of building into a toolchain for converion for example. I haven't found out yet whether it uses some form of xls to control the conversion which is customizable. David Cousens - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] How to manage documentation translations
> On Sep 11, 2018, at 1:45 PM, Geert Janssens > wrote: > > Somewhere in the long thread about future documentation directions the issue > of translating documentation was raised. Rightfully so, because this is > currently a very challenging task. > > The initial translation, while a huge job, is relatively straight forward: > one > takes the English docbook files and translates each paragraph and header, one > by one. In the end one ends up with the same docbook files in your language. > > Documentation updates on the other hand are more challenging. Whenever the > English document is changed the only clue as to what has changed is in the > git > logs. Git, while very powerful, is not very translator-friendly. It's > targeting a completely different use case. > > For translations other tools exist. The best-known to us is gettext. This > works by creating a message catalog of all translatable strings with tooling > to help in translating them. Whenever an original string changes it is > relatively easy for the translator to figure out which string has changed and > make the necessary changes in the translation as well. > > These two methods behave very differently in case of partially translated > documentation: > > * With our old method only documentation that has been translated in > available > in that language. Untranslated parts are not available at all. > * With the gettext method the full documentation is always presented to the > user. For parts that have been translated, this translation will be shown. > For > parts that have not been translated, the original English text will be shown. > > Also in the old method documentation doesn't move unless a translator makes > modifications. In the gettext method the translation may change whenever the > English original changes. And even a simple change of punctuation would hide > a > translation from the end user (at least that's what happened in our current > Italian translation, which is based on the gettext method). > > I honestly don't know which end result is preferred by non-English speaking > end users. Perhaps we should poll for this in our non-English mailing lists. > > That's what we have now and I think we should be able to do better. Both for > our translators as for our end users. > > In the light of the upcoming major rework of the guide, option one will end > in > a lot of translator frustration. Translators will be required to interpret > git > logs and diffs to learn what has happened. As said, git is not a very good > tool for non-developers to deal with. > > So I'm inclined to look for improvements in the gettext method. > > For the direct issues mentioned above: > 1. losing translations on something as simple as a punctuation change. > We could avoid this by not running gettext extraction automatically. In a way > that would make the gettext method a hybrid between the two methods. The > workflow would become: > a. a translator runs gettext > b. the translator looks for new/changes text and updates the translation. > c. this will be used from now on > d. until the translator reruns gettext. > => technical note, this really means we should copy/cache the original > English > documentation for each language we support. This copy/cache should only be > updated on request of the translator. > The advantages of this approach are > * all of gettext tooling is available to support the translator > * the translated documentation the end user sees will always be what the > translator intended and never change automatically behind the translator's > back. > Drawbacks: > * if the translation was not complete, there will be English parts in there > still. > * translator needs to be aware of the requirement to rerun gettext (or more > precisely to update the copy/cache) > > Another approach would be to tweak gettext behaviour to not hide slightly > altered (fuzzy) translations. > > 2. The presence of English text in partially translated documentation > We could again wrap around gettext and filter out untranslated parts. That > may > give odd results though so I wouldn't recommend it. > > Or we could leverage automated translations for example via google translate. > We would have to add a note the translation may be more unreliable in that > case. But perhaps poor translation is better than no translation at all ? > > That's as far as I got for now. More input and other ideas are welcome. FWIW searching "translate docbook documentation" produced a lot of pages involving gettext and none involving our whole-document approach. Regards, John Ralls ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
[GNC-dev] How to manage documentation translations
Somewhere in the long thread about future documentation directions the issue of translating documentation was raised. Rightfully so, because this is currently a very challenging task. The initial translation, while a huge job, is relatively straight forward: one takes the English docbook files and translates each paragraph and header, one by one. In the end one ends up with the same docbook files in your language. Documentation updates on the other hand are more challenging. Whenever the English document is changed the only clue as to what has changed is in the git logs. Git, while very powerful, is not very translator-friendly. It's targeting a completely different use case. For translations other tools exist. The best-known to us is gettext. This works by creating a message catalog of all translatable strings with tooling to help in translating them. Whenever an original string changes it is relatively easy for the translator to figure out which string has changed and make the necessary changes in the translation as well. These two methods behave very differently in case of partially translated documentation: * With our old method only documentation that has been translated in available in that language. Untranslated parts are not available at all. * With the gettext method the full documentation is always presented to the user. For parts that have been translated, this translation will be shown. For parts that have not been translated, the original English text will be shown. Also in the old method documentation doesn't move unless a translator makes modifications. In the gettext method the translation may change whenever the English original changes. And even a simple change of punctuation would hide a translation from the end user (at least that's what happened in our current Italian translation, which is based on the gettext method). I honestly don't know which end result is preferred by non-English speaking end users. Perhaps we should poll for this in our non-English mailing lists. That's what we have now and I think we should be able to do better. Both for our translators as for our end users. In the light of the upcoming major rework of the guide, option one will end in a lot of translator frustration. Translators will be required to interpret git logs and diffs to learn what has happened. As said, git is not a very good tool for non-developers to deal with. So I'm inclined to look for improvements in the gettext method. For the direct issues mentioned above: 1. losing translations on something as simple as a punctuation change. We could avoid this by not running gettext extraction automatically. In a way that would make the gettext method a hybrid between the two methods. The workflow would become: a. a translator runs gettext b. the translator looks for new/changes text and updates the translation. c. this will be used from now on d. until the translator reruns gettext. => technical note, this really means we should copy/cache the original English documentation for each language we support. This copy/cache should only be updated on request of the translator. The advantages of this approach are * all of gettext tooling is available to support the translator * the translated documentation the end user sees will always be what the translator intended and never change automatically behind the translator's back. Drawbacks: * if the translation was not complete, there will be English parts in there still. * translator needs to be aware of the requirement to rerun gettext (or more precisely to update the copy/cache) Another approach would be to tweak gettext behaviour to not hide slightly altered (fuzzy) translations. 2. The presence of English text in partially translated documentation We could again wrap around gettext and filter out untranslated parts. That may give odd results though so I wouldn't recommend it. Or we could leverage automated translations for example via google translate. We would have to add a note the translation may be more unreliable in that case. But perhaps poor translation is better than no translation at all ? That's as far as I got for now. More input and other ideas are welcome. Regards, Geert ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
Op maandag 10 september 2018 17:26:44 CEST schreef David T. via gnucash-devel: > The idea of use-case recipes sounds rather like the “walkthrough" described > in the pronovix article, which they clearly see as a specific, separate, > experience. Such resources have their place, but not in the Concept Guide. > Walkthroughs could use DocBook ENTITY mechanisms to cobble together > snippets of steps into a single sequence, but that makes my head hurt, so I > won’t be the one taking that project on. > You don't have to of course. I'm happy with your current initiative as well. Geert ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
Op dinsdag 11 september 2018 15:13:51 CEST schreef David T.: > Hello, > > > On Sep 11, 2018, at 4:45 AM, Geert Janssens > > wrote:> > > Op dinsdag 11 september 2018 09:15:43 CEST schreef David Cousens: > >> David, > >> > >> Just some comments on a couple of other points: > >> > >> Embedding even the context help in the program code is not a really good > >> idea. It means that text cannot be edited /altered easily separately from > >> the program and without rebuilding the program. > > > > You raise a good point here. Aside from the building restriction (which we > > now also have for source message translations), it would probably limit > > the potential help writing contributors to only those people capable of > > parsing the source code. In practice there would be few outside of the > > developers themselves. And those are known not to be the best > > documentation writers :( > Geert, you note that the developers are not proficient documentors, and I > agree with you. You also say that you’d prefer the broader documentation > team (such as it is) to be able to edit this context help. > > One major reason for my suggesting that context help be embedded in code is > a direct response to the current situation, where well-intentioned > documentation contributors have placed duplicative information in > *different places.* Deciding when a “small piece of prose” (as you put it, > Geert) crosses that magical threshold from context help into concept guide > is precisely what has led this documentation into the mess it’s in. > Although it’s perhaps heresy, I think that limiting the ability of the > Documentation Team to make contributions to the Help might not be a bad > idea. Push everyone to the Guide, instead. Well, that's one way of looking at it. I think the main reason why we have duplication is because there hasn't been anyone who took responsibility for the documentation in years and perhaps there never was. Someone to set clear directions and guard them. Someone that would review contributions and direct contributors in the right direction. John and I do this for the code, but there's no one doing that for documentation really. As such I'm very pleased with your initiative to clarify the boundaries of documentation. And frankly I don't really care that much what those are in detail. As long as it works as a clear framework for anyone interested in contributing. And that it will be backed by a couple of people to guide new contributors. I understand you and David Cousens are willing to rework the existing documentation. Great! Are you also willing to review work done by others and tell them to relocate if their initial suggestion isn't right ? > > I envision that the context help would consist of short _functional_ > descriptions of one or two sentences. I believe that the rate of change in > the functions of the UI elements is exceedingly small. In my decade-plus > time using GnuCash, I haven’t seen many changes to the buttons or screens. > Accounting hasn’t suddenly come up with an entirely new set of functions. > This leads me to the conclusion that functional descriptions of those > buttons and screens won’t need to change either. If the functional aspects > of the interface don’t change, then the context help doesn’t need to > change, either. If the content isn’t changing, then the authorial skill of > developers is beside the point. > > In other words, unless there is a change in function, there is no need to > change the functional description. It seems to me that putting text that > doesn’t change into code is essentially a one-time process. Not necessarily > easy, but once completed, not particularly obtrusive. Putting the > functional description into code has the added benefit, perhaps, of > alerting developers to the fact that if they change a feature, the > description (right there in the code) needs an update as well. As for the context help in particular, this discussion is too abstract for me. I have a feeling you and I are thinking of different things when we write about context help or how to handle it. In addition I worry we're trying to change too much at once. You started with the goal of deduplicating content and for that you propose to move most content from help to guide. I'm all with you. I propose to do that first and *then* see what remains of the help document and decide what to do with it. > > So I vote for keeping all help consisting of more than a single sentence > > in a separate document. So a short tooltip or a hint in an empty text > > entry go into the code (also for practical reasons), but a small piece of > > prose explaining how a certain dialog window works should go in a > > document that is more easily edited by documentation writers. > > > > What we may be able to do is write some scripts that would automatically > > extract a list of all user interface elements from the source code and > > compose a skeleton document from this.
Re: [GNC-dev] Long Term Documentation Directions
Yes, sorry. I misspoke on that last point. Regards, Adrien > On Sep 11, 2018, at 1:10 PM, David T. wrote: > > Adrien, > > I’ll note here that you seem to have the documentation model backwards, > insofar as you suggest that interface changes wouldn’t affect the Guide. I > believe that such changes would not affect the Help, whereas changes in the > UI and the form and location of a given widget would definitely be reflected > in the Guide, since that is where the descriptive explanation of GnuCash and > its functions will reside. The Help would only consist of context help > containing a sentence or two about that widget. > > David > ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
Adrien, > On Sep 11, 2018, at 1:09 PM, Adrien Monteleone > wrote: > > > >> On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel >> wrote: >> >> Hello, >> >> >> I envision that the context help would consist of short _functional_ >> descriptions of one or two sentences. I believe that the rate of change in >> the functions of the UI elements is exceedingly small. In my decade-plus >> time using GnuCash, I haven’t seen many changes to the buttons or screens. >> Accounting hasn’t suddenly come up with an entirely new set of functions. >> This leads me to the conclusion that functional descriptions of those >> buttons and screens won’t need to change either. If the functional aspects >> of the interface don’t change, then the context help doesn’t need to change, >> either. If the content isn’t changing, then the authorial skill of >> developers is beside the point. >> >> In other words, unless there is a change in function, there is no need to >> change the functional description. It seems to me that putting text that >> doesn’t change into code is essentially a one-time process. Not necessarily >> easy, but once completed, not particularly obtrusive. Putting the functional >> description into code has the added benefit, perhaps, of alerting developers >> to the fact that if they change a feature, the description (right there in >> the code) needs an update as well. > > While the principles might not change, or even the name/label of certain > buttons, the UI layout (where those buttons are, the fact that they are > buttons instead of menu entries, etc.) will very likely change as the Gnome > HIG is more faithfully implemented. But those code changes shouldn’t affect > anything generally in the Guide, and should auto update the context help if > it is drawn from the code itself. If not, then consider that attempts to > corral GnuCash within the confines of the Gnome HIG, will produce such > changes you’re thinking won’t happen. > We are in general agreement here. My point was that any context help text, being based on the *actual function* of a given widget (and regardless of the form or broader context of that widget) is unlikely to change. Geert was concerned that embedding help text in code would shield that text from the editorial expertise of members of the Documentation Team. I was trying to point out that these texts, once written, are unlikely to need rewriting unless the actual functions change. I’ll note here that you seem to have the documentation model backwards, insofar as you suggest that interface changes wouldn’t affect the Guide. I believe that such changes would not affect the Help, whereas changes in the UI and the form and location of a given widget would definitely be reflected in the Guide, since that is where the descriptive explanation of GnuCash and its functions will reside. The Help would only consist of context help containing a sentence or two about that widget. David > Regards, > Adrien > ___ > gnucash-devel mailing list > gnucash-devel@gnucash.org > https://lists.gnucash.org/mailman/listinfo/gnucash-devel ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
I don't know about allowing room for it, but it's pretty far in the future because we still have too many Gnome dependencies in the core and too many MVC violations to be able to implement a different toolkit. Regards, John Ralls > On Sep 11, 2018, at 10:23 AM, Adrien Monteleone > wrote: > > Then I misunderstood some earlier discussions about the UI, at least with > respect to Linux. What toolkit is envisioned to be used? What layout > principles? Or are those questions so far in the future as to not be worth > spending time allowing room for? > > Regards, > Adrien > >> On Sep 11, 2018, at 12:18 PM, John Ralls wrote: >> >> >> >>> On Sep 11, 2018, at 10:09 AM, Adrien Monteleone >>> wrote: >>> >>> >>> On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel wrote: Hello, I envision that the context help would consist of short _functional_ descriptions of one or two sentences. I believe that the rate of change in the functions of the UI elements is exceedingly small. In my decade-plus time using GnuCash, I haven’t seen many changes to the buttons or screens. Accounting hasn’t suddenly come up with an entirely new set of functions. This leads me to the conclusion that functional descriptions of those buttons and screens won’t need to change either. If the functional aspects of the interface don’t change, then the context help doesn’t need to change, either. If the content isn’t changing, then the authorial skill of developers is beside the point. In other words, unless there is a change in function, there is no need to change the functional description. It seems to me that putting text that doesn’t change into code is essentially a one-time process. Not necessarily easy, but once completed, not particularly obtrusive. Putting the functional description into code has the added benefit, perhaps, of alerting developers to the fact that if they change a feature, the description (right there in the code) needs an update as well. >>> >>> While the principles might not change, or even the name/label of certain >>> buttons, the UI layout (where those buttons are, the fact that they are >>> buttons instead of menu entries, etc.) will very likely change as the Gnome >>> HIG is more faithfully implemented. But those code changes shouldn’t affect >>> anything generally in the Guide, and should auto update the context help if >>> it is drawn from the code itself. If not, then consider that attempts to >>> corral GnuCash within the confines of the Gnome HIG, will produce such >>> changes you’re thinking won’t happen. >> >> Why do you think we're going to "more faithfully implement" the Gnome HIG? >> One of our long-term goals is to remove our Gnome dependencies. >> >> Regards, >> John Ralls > > > ___ > gnucash-devel mailing list > gnucash-devel@gnucash.org > https://lists.gnucash.org/mailman/listinfo/gnucash-devel ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
> On Sep 11, 2018, at 8:13 AM, David Cousens wrote: > > Hi Geert > > "I know you can define these links in docbook. However my remark earlier in > this thread is how will they work in practice ? How can one document on the > system know where the other is stored ? I presume this means we should have > strict rules about the relative locations of documents. And those should be > communicated properly to gnucash-documentation packagers for various > distributions" > > The links between different docbook documents can be handled with XML > catalogues. > It looks like you define generic paths for links during the document build > and use those generic names as the URLs in the code you call to bring them > up in the program. The generic names are linked by xsltprocto the actual > URLs in the catalog.xml file which resides by default in /etc/xml/catalog > but can be redirected to something like /usr/share/gnucash/xml/catalog.xml > with an environment variable XML_CATALOGUE_FILE during the document build. > xsltproc appears to construct the links between the files. Not sure how the > program handles that. I'll keep digging to see what i can come up with. > > Not sure about what happens with the PDF etc but I think xsltproc uses > specific xsl files to process them the same as it does now. > > (http://sagehill.net/docbookxsl/Catalogs.html#WhyCatalogs) Well, it's "PDF etc" (where etc. means the various HTML formats including epub, mobi, and chm, in which most users read the docs) that's the issue. Only Yelp directly reads Docbook-formatted documents, so that's not useful to most of our users. Docbook may well be the eighth wonder of the documentation world but for our purposes it's only a way of marking up document sources. We can't use any of its feature that don't map to HTML and PDF. Regards, John Ralls ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
Then I misunderstood some earlier discussions about the UI, at least with respect to Linux. What toolkit is envisioned to be used? What layout principles? Or are those questions so far in the future as to not be worth spending time allowing room for? Regards, Adrien > On Sep 11, 2018, at 12:18 PM, John Ralls wrote: > > > >> On Sep 11, 2018, at 10:09 AM, Adrien Monteleone >> wrote: >> >> >> >>> On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel >>> wrote: >>> >>> Hello, >>> >>> >>> I envision that the context help would consist of short _functional_ >>> descriptions of one or two sentences. I believe that the rate of change in >>> the functions of the UI elements is exceedingly small. In my decade-plus >>> time using GnuCash, I haven’t seen many changes to the buttons or screens. >>> Accounting hasn’t suddenly come up with an entirely new set of functions. >>> This leads me to the conclusion that functional descriptions of those >>> buttons and screens won’t need to change either. If the functional aspects >>> of the interface don’t change, then the context help doesn’t need to >>> change, either. If the content isn’t changing, then the authorial skill of >>> developers is beside the point. >>> >>> In other words, unless there is a change in function, there is no need to >>> change the functional description. It seems to me that putting text that >>> doesn’t change into code is essentially a one-time process. Not necessarily >>> easy, but once completed, not particularly obtrusive. Putting the >>> functional description into code has the added benefit, perhaps, of >>> alerting developers to the fact that if they change a feature, the >>> description (right there in the code) needs an update as well. >> >> While the principles might not change, or even the name/label of certain >> buttons, the UI layout (where those buttons are, the fact that they are >> buttons instead of menu entries, etc.) will very likely change as the Gnome >> HIG is more faithfully implemented. But those code changes shouldn’t affect >> anything generally in the Guide, and should auto update the context help if >> it is drawn from the code itself. If not, then consider that attempts to >> corral GnuCash within the confines of the Gnome HIG, will produce such >> changes you’re thinking won’t happen. > > Why do you think we're going to "more faithfully implement" the Gnome HIG? > One of our long-term goals is to remove our Gnome dependencies. > > Regards, > John Ralls ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
> On Sep 11, 2018, at 10:09 AM, Adrien Monteleone > wrote: > > > >> On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel >> wrote: >> >> Hello, >> >> >> I envision that the context help would consist of short _functional_ >> descriptions of one or two sentences. I believe that the rate of change in >> the functions of the UI elements is exceedingly small. In my decade-plus >> time using GnuCash, I haven’t seen many changes to the buttons or screens. >> Accounting hasn’t suddenly come up with an entirely new set of functions. >> This leads me to the conclusion that functional descriptions of those >> buttons and screens won’t need to change either. If the functional aspects >> of the interface don’t change, then the context help doesn’t need to change, >> either. If the content isn’t changing, then the authorial skill of >> developers is beside the point. >> >> In other words, unless there is a change in function, there is no need to >> change the functional description. It seems to me that putting text that >> doesn’t change into code is essentially a one-time process. Not necessarily >> easy, but once completed, not particularly obtrusive. Putting the functional >> description into code has the added benefit, perhaps, of alerting developers >> to the fact that if they change a feature, the description (right there in >> the code) needs an update as well. > > While the principles might not change, or even the name/label of certain > buttons, the UI layout (where those buttons are, the fact that they are > buttons instead of menu entries, etc.) will very likely change as the Gnome > HIG is more faithfully implemented. But those code changes shouldn’t affect > anything generally in the Guide, and should auto update the context help if > it is drawn from the code itself. If not, then consider that attempts to > corral GnuCash within the confines of the Gnome HIG, will produce such > changes you’re thinking won’t happen. Why do you think we're going to "more faithfully implement" the Gnome HIG? One of our long-term goals is to remove our Gnome dependencies. Regards, John Ralls ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
> On Sep 11, 2018, at 8:13 AM, David T. via gnucash-devel > wrote: > > Hello, > > > I envision that the context help would consist of short _functional_ > descriptions of one or two sentences. I believe that the rate of change in > the functions of the UI elements is exceedingly small. In my decade-plus time > using GnuCash, I haven’t seen many changes to the buttons or screens. > Accounting hasn’t suddenly come up with an entirely new set of functions. > This leads me to the conclusion that functional descriptions of those buttons > and screens won’t need to change either. If the functional aspects of the > interface don’t change, then the context help doesn’t need to change, either. > If the content isn’t changing, then the authorial skill of developers is > beside the point. > > In other words, unless there is a change in function, there is no need to > change the functional description. It seems to me that putting text that > doesn’t change into code is essentially a one-time process. Not necessarily > easy, but once completed, not particularly obtrusive. Putting the functional > description into code has the added benefit, perhaps, of alerting developers > to the fact that if they change a feature, the description (right there in > the code) needs an update as well. While the principles might not change, or even the name/label of certain buttons, the UI layout (where those buttons are, the fact that they are buttons instead of menu entries, etc.) will very likely change as the Gnome HIG is more faithfully implemented. But those code changes shouldn’t affect anything generally in the Guide, and should auto update the context help if it is drawn from the code itself. If not, then consider that attempts to corral GnuCash within the confines of the Gnome HIG, will produce such changes you’re thinking won’t happen. Regards, Adrien ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
Hi Geert "I know you can define these links in docbook. However my remark earlier in this thread is how will they work in practice ? How can one document on the system know where the other is stored ? I presume this means we should have strict rules about the relative locations of documents. And those should be communicated properly to gnucash-documentation packagers for various distributions" The links between different docbook documents can be handled with XML catalogues. It looks like you define generic paths for links during the document build and use those generic names as the URLs in the code you call to bring them up in the program. The generic names are linked by xsltprocto the actual URLs in the catalog.xml file which resides by default in /etc/xml/catalog but can be redirected to something like /usr/share/gnucash/xml/catalog.xml with an environment variable XML_CATALOGUE_FILE during the document build. xsltproc appears to construct the links between the files. Not sure how the program handles that. I'll keep digging to see what i can come up with. Not sure about what happens with the PDF etc but I think xsltproc uses specific xsl files to process them the same as it does now. (http://sagehill.net/docbookxsl/Catalogs.html#WhyCatalogs) Cheers David Cousens - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Finding wiki orphans
Perhaps • Bazaar • BreezyBadgerInstallation • Main Page could be deleted by someone with those tights on the wiki? David T. > On Sep 11, 2018, at 2:46 AM, Frank H. Ellenberger > wrote: > > Am 11.09.2018 um 06:03 schrieb David Cousens: >> One other problem with a WIki for a maintenance >> point of view is thatt a link to a page can be deleted and the page becomes >> an orphan with no way to logically access it. A search negine will sometimes >> find orphan pages in a wiki. > > Not really, there is a special page: > https://wiki.gnucash.org/wiki/Special:LonelyPages > > And if a page has the magic word __NOINDEX__, no search engine should > find it. > > HTH > Frank > > ___ > 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] Finding wiki orphans
Thanks Frank, I didn't know about the Lonely pages . that helps a lot. David Cousens - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Finding wiki orphans
On Tue, 2018-09-11 at 08:46 +0200, Frank H. Ellenberger wrote: > Am 11.09.2018 um 06:03 schrieb David Cousens: > > One other problem with a WIki for a maintenance > > point of view is thatt a link to a page can be deleted and the page becomes > > an orphan with no way to logically access it. A search negine will sometimes > > find orphan pages in a wiki. > > Not really, there is a special page: > https://wiki.gnucash.org/wiki/Special:LonelyPages > > And if a page has the magic word __NOINDEX__, no search engine should > find it. > > HTH > Frank > ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
Hello, > On Sep 11, 2018, at 4:45 AM, Geert Janssens > wrote: > > Op dinsdag 11 september 2018 09:15:43 CEST schreef David Cousens: >> David, >> >> Just some comments on a couple of other points: >> >> Embedding even the context help in the program code is not a really good >> idea. It means that text cannot be edited /altered easily separately from >> the program and without rebuilding the program. > > You raise a good point here. Aside from the building restriction (which we > now > also have for source message translations), it would probably limit the > potential help writing contributors to only those people capable of parsing > the source code. In practice there would be few outside of the developers > themselves. And those are known not to be the best documentation writers :( > Geert, you note that the developers are not proficient documentors, and I agree with you. You also say that you’d prefer the broader documentation team (such as it is) to be able to edit this context help. One major reason for my suggesting that context help be embedded in code is a direct response to the current situation, where well-intentioned documentation contributors have placed duplicative information in *different places.* Deciding when a “small piece of prose” (as you put it, Geert) crosses that magical threshold from context help into concept guide is precisely what has led this documentation into the mess it’s in. Although it’s perhaps heresy, I think that limiting the ability of the Documentation Team to make contributions to the Help might not be a bad idea. Push everyone to the Guide, instead. I envision that the context help would consist of short _functional_ descriptions of one or two sentences. I believe that the rate of change in the functions of the UI elements is exceedingly small. In my decade-plus time using GnuCash, I haven’t seen many changes to the buttons or screens. Accounting hasn’t suddenly come up with an entirely new set of functions. This leads me to the conclusion that functional descriptions of those buttons and screens won’t need to change either. If the functional aspects of the interface don’t change, then the context help doesn’t need to change, either. If the content isn’t changing, then the authorial skill of developers is beside the point. In other words, unless there is a change in function, there is no need to change the functional description. It seems to me that putting text that doesn’t change into code is essentially a one-time process. Not necessarily easy, but once completed, not particularly obtrusive. Putting the functional description into code has the added benefit, perhaps, of alerting developers to the fact that if they change a feature, the description (right there in the code) needs an update as well. > So I vote for keeping all help consisting of more than a single sentence in a > separate document. So a short tooltip or a hint in an empty text entry go > into > the code (also for practical reasons), but a small piece of prose explaining > how a certain dialog window works should go in a document that is more easily > edited by documentation writers. > > What we may be able to do is write some scripts that would automatically > extract a list of all user interface elements from the source code and > compose > a skeleton document from this. Then with some clever msgmerge like magic > merge > existing help strings from a previous version of this document. That would at > least make sure the list of interface elements can be kept up to date > programmatically so no one should scan the sources manually for changes. > Keeping in mind that the Help is meant to be *contextual*—that is, linked directly to the screens and widgets a user encounters in GnuCash—perhaps the Help document should be more strictly structured to reflect this. Set it up as a table, with a column that provides the link to the interface, a column for the (brief) help text, and a column to link to the guide. This sort of structure exists already in some places of the Help; converting the entire document to this format would make clear to future writers and users that the Help is primarily meant for access from the application. People looking for more explanation would be directed to the Concept Guide. In an absolute sense, there is no real need for chapter headings, screen titles, figures, etc., since user access to this document would strictly be from the application itself. You could, I guess, go the other direction, and create separate files for each individual entry. To me, madness lies down that alley. > >> My understanding is that it >> can be done from a docbook that just has the links to a section which is >> displayed in response to a help button being pressed or something like a >> Shift-F1 key combination while the focus is on the button/checkbox/etc that >> you want help on. It could be a separate window from the main
Re: [GNC-dev] Long Term Documentation Directions
Op dinsdag 11 september 2018 09:15:43 CEST schreef David Cousens: > David, > > Just some comments on a couple of other points: > > Embedding even the context help in the program code is not a really good > idea. It means that text cannot be edited /altered easily separately from > the program and without rebuilding the program. You raise a good point here. Aside from the building restriction (which we now also have for source message translations), it would probably limit the potential help writing contributors to only those people capable of parsing the source code. In practice there would be few outside of the developers themselves. And those are known not to be the best documentation writers :( So I vote for keeping all help consisting of more than a single sentence in a separate document. So a short tooltip or a hint in an empty text entry go into the code (also for practical reasons), but a small piece of prose explaining how a certain dialog window works should go in a document that is more easily edited by documentation writers. What we may be able to do is write some scripts that would automatically extract a list of all user interface elements from the source code and compose a skeleton document from this. Then with some clever msgmerge like magic merge existing help strings from a previous version of this document. That would at least make sure the list of interface elements can be kept up to date programmatically so no one should scan the sources manually for changes. > My understanding is that it > can be done from a docbook that just has the links to a section which is > displayed in response to a help button being pressed or something like a > Shift-F1 key combination while the focus is on the button/checkbox/etc that > you want help on. It could be a separate window from the main help system > which just pops up displays the information and closes when you finish (i.e > no navigation - want help on something else-click on something else and hit > shift F10 - but pulls its text from a HTML file created from a > docbook/asciidoc or similar source help file. It would not necessarily have > to have such a file broken up into subfiles. > > The same would also be true of the Concepts guide. It could be modules > within a single file or a collection of files which can either be displayed > independently or linked together to form a full document. The existing Help > manual are organised a bit like that but the separate files for the chapters > do not have document headers so they can't be displayed independently . > What I mean by that is you can point a browser at the derived HTML file for > a chapter and have it display just that chapter without having to load the > whole Help manual and navigate to the bit you want. In any case breaking it > into separate source files is not a high priority but it may make some > sense to have related content in its own module futher down the track. It > can also be done progressively once the content has been rearranged. > Indeed. We should primarily find a way it remains manageable for translators. > Walk throughs on the other hand require a considerable code effort and have > to be embedded in the code completely. They need an engine which can drive > the interfaceand either feed data in or better still request the user to > enter the data. The one I am most familiar with is in the Flight Gear > flight simulator on Linux. It is just like a flying instructor taking you > through the check list before takeoff. While it would be nice I doubt if it > would really be feasible. > Agreed. Walk throughs ad described on the link David passed are not planned in the foreseeable future. What I was hinting at in my suggestions is more documentation formatted as explained in: https://www.youtube.com/watch? v=7amYpQWhz3o=57=PLaVkMRyQacUQYxXkzvcZJm-kc_FEJpkxK=0s But to be clear: I won't be doing the documentation restructuring/writing, so neither will I dictate what format and content the guide should be. I'm fine with the current high level proposals. I do care about maintainability beyond the initial restructuring/rewriting effort so if I find issues in that area, you'll hear me :) In that context I think we should make documentation translation a separate thread. The current one is getting hard to follow. Regards, Geert ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
David, Just some comments on a couple of other points: Embedding even the context help in the program code is not a really good idea. It means that text cannot be edited /altered easily separately from the program and without rebuilding the program. My understanding is that it can be done from a docbook that just has the links to a section which is displayed in response to a help button being pressed or something like a Shift-F1 key combination while the focus is on the button/checkbox/etc that you want help on. It could be a separate window from the main help system which just pops up displays the information and closes when you finish (i.e no navigation - want help on something else-click on something else and hit shift F10 - but pulls its text from a HTML file created from a docbook/asciidoc or similar source help file. It would not necessarily have to have such a file broken up into subfiles. The same would also be true of the Concepts guide. It could be modules within a single file or a collection of files which can either be displayed independently or linked together to form a full document. The existing Help manual are organised a bit like that but the separate files for the chapters do not have document headers so they can't be displayed independently . What I mean by that is you can point a browser at the derived HTML file for a chapter and have it display just that chapter without having to load the whole Help manual and navigate to the bit you want. In any case breaking it into separate source files is not a high priority but it may make some sense to have related content in its own module futher down the track. It can also be done progressively once the content has been rearranged. Walk throughs on the other hand require a considerable code effort and have to be embedded in the code completely. They need an engine which can drive the interfaceand either feed data in or better still request the user to enter the data. The one I am most familiar with is in the Flight Gear flight simulator on Linux. It is just like a flying instructor taking you through the check list before takeoff. While it would be nice I doubt if it would really be feasible. David Cousens - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Re: [GNC-dev] Long Term Documentation Directions
Op dinsdag 11 september 2018 06:03:28 CEST schreef David Cousens: > This link (http://www.sagehill.net/docbookxsl/Db5Tools.html) provides the > mechanism for linking between different docbooks. It would probably a good > idea to mark any docbook links with a do not delete message for example. so > that editors are aware they may break any linked structure, > I know you can define these links in docbook. However my remark earlier in this thread is how will they work in practice ? How can one document on the system know where the other is stored ? I presume this means we should have strict rules about the relative locations of documents. And those should be communicated properly to gnucash-documentation packagers for various distributions. And how would those cross-references appear in our PDF/epub/ mobi versions of the documentation ? So while I suppose this can all be solved, it will come with a few challenges on its own and requires coordination outside the gnucash project. > I am willing to help with the task of reorganizing the above if the decision > is made to go ahead. Yay! Geert ___ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
