Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
On 2020-05-06 20:46, Adrien Monteleone wrote: > I’ve found myself searching the docs just to find a reference to point to, > and then either found the docs lacking, not clear, or the search simply > taking longer than just typing out an answer. I’m not sure if there is a > resolution for such cases. They may always exist. The traditional way, in companies where I've worked, is to enter a bug report against the documentation, preferably with specific suggested text and specific reference to where it belongs. At least that way the information is not lost. And it's only a little more work than answering a person in a mailing list. That doesn't solve the problem of long-standing bugs not getting fixed. I don't have a good solution or that, in an environment where the documenters, like the coders, are all volunteers and get to pick and choose what they want to work on, without necessarily basing that choice on what will benefit the greatest number of users. -- Regards, Stan Brown Tehachapi, CA, USA https://BrownMath.com https://OakRoadSystems.com ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All.
Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
Adrien, The wiki is currently an entry point for your Group 2 people to provide input and it is a route already in place to migrate documentation from the wiki to the formal docs. I am in the process of migrating the trading accounts documentation although what was in the wiki was not much more than a note. Even the wiki requires you to learn a basic language although it is much like AsciiDoc. I ended up doing documentation after i had made a few minor code changes and realized no-one was likely to know about them unless I incorporated it into the documentation and in doing so realized a lot of other things in the same area were not very completely documented. I still make mistakes in the process of the documentation that Frank and others will attest to. I had no knowledge of DocBooks when I started a couple of years ago and I'm still learning. I am not sure that AsciiDoc is necessarily any less of a committment than learning DocBook although some of its basic concepts are fairly simple. OK once you know it it's no problem. Having to use complete tags in XML is a bit of a pain but I find myself cutting and pasting common structural elements rather than typing them in all the time. A nice editor with tag completion would certainly not go astray. I tried one but it doesn't pick up on the gnucash DTD as it is not in the same directory as the guide or help sources in the current source structure. AsciiDoc can actually generate formal DocBook output and it is meant to be semantically equivalent so it should be possible to use it as a development tool however it won't know about the GnuCash specific structures and how they link to each other. It has some similarities (and differences) to the wiki markup language. If you are going to contribute to the docs I think it is unavoiable having to invest time in the toolchain, whatever it happens to be. Most of the toolchain is pretty transparent once you have configured a build directory its just make check make html (or pdf or epub or mobi or all of them) and then view what you have written once you have located the newly written output. I don't think one can avoid the github repository either or the process of submitting PR's to it from a personal repository in an environment when multiple people on multiple continents in different time zones are contributing changes and those changes have to be reviewed and organized to match and be consistent with code releases etc etc. I am still a git and github novice as John and Frank will attest but there are tools that make that a lot easier too (Gitkraken has made my lack of skill with raw git/github look a lot less clumsy). Likewise using the Bugzilla for flagging documentation changes. A user can always submit the documentation changes they want to suggest as raw text in Bugzilla. I am not opposed in principle to changing but I do think we need to ensure we will all be better off after any change. David - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-User-f1415819.html ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All.
Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
Yes, I admit, I’m guilty in many cases of long-winded explanations and examples rather than simply referencing the docs. I have done that a few times, especially where I recall a recent thread on the same subject. I think overall, referencing docs is preferable. I’ve found myself searching the docs just to find a reference to point to, and then either found the docs lacking, not clear, or the search simply taking longer than just typing out an answer. I’m not sure if there is a resolution for such cases. They may always exist. I’m contemplating some mechanism beyond the list or bug reports where seasoned users can officially contribute text for the docs without having to make the investment in learning build tools that they have no use for otherwise. Maybe the wiki is enough? I’ve seen projects that use a wiki for documentation. I know some present GC documentarians frown upon such a thing, but perhaps rather than being a substitute or replacement, if it functioned as a bridge, we could all benefit. (I’m certainly not tied to any one option, I’m just mentioning it since we already have a wiki) That process would have to be formalized and outlined though. At least *some* current documentarians would need to agree to try to first: incorporate ‘wiki documentation’ into the official flow, rather than just continuing to let them wither. Maybe the process is to: 1. File the bug 2. Propose text via the wiki (maybe in a special place, with special notation, or some other wiki facility) 3. Discuss the change in Bugzilla 4. Formally create the change with the current toolchain 5. Submit the PR 6. Docs get updated 3–5 would involve ‘Group 1’ and 1-3 would involve ‘Group 2’. Devs are involved in any step, but are the only ones to determine step 6 just as they are now. Presently, step 2 or something like it does not really exist, hence the ‘gap’. Regards, Adrien > On May 6, 2020 w19d127, at 10:22 PM, D. wrote: > > Adrien, > > Being a past member of group 1, I can vouch for the challenges that the > current tool set presents. Some might even call me the poster child on how > difficult it can be. It does meet numerous disparate needs, however. > > Your group 2 users can and do contribute-- to the wiki and the user list. > Remember that the GnuCash "culture" is to recommend reading the docs, check > the wiki, and check the mailing list archives. > > I agree that there are disconnects and gaps. For example, stuff seems to get > into the wiki and never go any further-- and they often remain in the wiki > long after the documents get updated. Similarly, mailing list threads rarely > migrate. To me, this is where the significant disconnect lies: in the fact > that ideas discussed here in the lists rarely go further to the wiki and the > docs. > > Underlying this, I think, is a sense that the docs are incomplete or inferior > or outdated, and the best way to answer a problem is to ask on the lists. The > tendency in the community is to reinforce this sense, unintentionally > perhaps, by repeatedly answering basic questions in lengthy email threads, > rather than either referring users to the existing documentation or by > migrating the knowledge in those threads into the documentation. I know that > you've been active in taking this on, and that the other Diligent Davids have > been working to get major areas of the documentation updated, so all is not > lost! > > David T. > Former documentarian ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All.
Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
Adrien, Being a past member of group 1, I can vouch for the challenges that the current tool set presents. Some might even call me the poster child on how difficult it can be. It does meet numerous disparate needs, however. Your group 2 users can and do contribute-- to the wiki and the user list. Remember that the GnuCash "culture" is to recommend reading the docs, check the wiki, and check the mailing list archives. I agree that there are disconnects and gaps. For example, stuff seems to get into the wiki and never go any further-- and they often remain in the wiki long after the documents get updated. Similarly, mailing list threads rarely migrate. To me, this is where the significant disconnect lies: in the fact that ideas discussed here in the lists rarely go further to the wiki and the docs. Underlying this, I think, is a sense that the docs are incomplete or inferior or outdated, and the best way to answer a problem is to ask on the lists. The tendency in the community is to reinforce this sense, unintentionally perhaps, by repeatedly answering basic questions in lengthy email threads, rather than either referring users to the existing documentation or by migrating the knowledge in those threads into the documentation. I know that you've been active in taking this on, and that the other Diligent Davids have been working to get major areas of the documentation updated, so all is not lost! David T. Former documentarian Original Message From: Adrien Monteleone Sent: Thu May 07 05:49:14 GMT+05:30 2020 To: Gnucash Users Subject: Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org > On May 6, 2020 w19d127, at 5:53 PM, David Cousens > wrote: > > The existing tool chain meets more than the need for a single document. There > is translation into multiple languages, online versions, standalone pdf, > epub etc. The Read theDoc' format is certainly quite nice but to be a > replacement candidate for the current tool stream it has to offer > considerable advantages over the current process while still meeting those > needs. Maybe these can all be met with an alternative but his needs to be > ascertained. > > The current documenters have invested time and effort in coming to grips > with what we currently use. Replacing part of the current tool chain means > we are going to have to put time and effort into learning a new approach > when in most case our available time for working on the documentation is > better spent exploring GnuCash and how it works and the underlying code. It > is not as though we are particularly well resourced in this area. Sounds to me like there are at least two perspectives here: 1. Current documenters who have invested in the current toolchain but don’t have all the info necessary to re-write the docs. 2. Users who can provide the info for documentation based on how the app works in their experience (at the user level, not necessarily at a code level) but who haven’t invested in the toolchain and for whom such an investment is out of their scope, wheelhouse, time available, etc. There is clearly a disconnect and a gap. How to bridge it? I’ll posit there doesn’t need to be ‘one toolchain to rule them all’ though that isn’t precluded should such a solution be discovered. Perhaps there should be another entry-point for Group #2 where they can submit documentation improvements on no simpler a basis than standard word processing, wiki editing, markdown etc. Then Group #1 takes that revised or newly added text and “sausages it” through the current project-preferred toolchain. Presently, either you join Group 1, or you don’t contribute and the docs stay stale or incomplete. Non-techy users can ask questions and report issues here on the list, and on Bugzilla. Maybe some similar process should be outlined for documentation and not just for functionality. (I know one can already file documentation bugs, the point is to clearly spell out that a similar process for documentation exists, or will.) Is there no room for offering Group 2 an easier point of entry? Is there an option which doesn’t require Group 1 to have to re-invest time in a different toolchain? Regards, Adrien > I support Frank's approach of defining and documenting what it is the > documentation currently does and needs to do then looking at what the > advantages/disadvantages of any alternative approach to the current tool > chain actually are and whether it can mmet all the current needs. In doing > this we also need to examine who is currently working on the documentation > and how they might react to a significant tool change. If a major effect is > we lose a significant part of the current resource base in this area, is it > really productive to make a change unless that change is really necessary > and increases the resource
Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
> On May 6, 2020 w19d127, at 5:53 PM, David Cousens > wrote: > > The existing tool chain meets more than the need for a single document. There > is translation into multiple languages, online versions, standalone pdf, > epub etc. The Read theDoc' format is certainly quite nice but to be a > replacement candidate for the current tool stream it has to offer > considerable advantages over the current process while still meeting those > needs. Maybe these can all be met with an alternative but his needs to be > ascertained. > > The current documenters have invested time and effort in coming to grips > with what we currently use. Replacing part of the current tool chain means > we are going to have to put time and effort into learning a new approach > when in most case our available time for working on the documentation is > better spent exploring GnuCash and how it works and the underlying code. It > is not as though we are particularly well resourced in this area. Sounds to me like there are at least two perspectives here: 1. Current documenters who have invested in the current toolchain but don’t have all the info necessary to re-write the docs. 2. Users who can provide the info for documentation based on how the app works in their experience (at the user level, not necessarily at a code level) but who haven’t invested in the toolchain and for whom such an investment is out of their scope, wheelhouse, time available, etc. There is clearly a disconnect and a gap. How to bridge it? I’ll posit there doesn’t need to be ‘one toolchain to rule them all’ though that isn’t precluded should such a solution be discovered. Perhaps there should be another entry-point for Group #2 where they can submit documentation improvements on no simpler a basis than standard word processing, wiki editing, markdown etc. Then Group #1 takes that revised or newly added text and “sausages it” through the current project-preferred toolchain. Presently, either you join Group 1, or you don’t contribute and the docs stay stale or incomplete. Non-techy users can ask questions and report issues here on the list, and on Bugzilla. Maybe some similar process should be outlined for documentation and not just for functionality. (I know one can already file documentation bugs, the point is to clearly spell out that a similar process for documentation exists, or will.) Is there no room for offering Group 2 an easier point of entry? Is there an option which doesn’t require Group 1 to have to re-invest time in a different toolchain? Regards, Adrien > I support Frank's approach of defining and documenting what it is the > documentation currently does and needs to do then looking at what the > advantages/disadvantages of any alternative approach to the current tool > chain actually are and whether it can mmet all the current needs. In doing > this we also need to examine who is currently working on the documentation > and how they might react to a significant tool change. If a major effect is > we lose a significant part of the current resource base in this area, is it > really productive to make a change unless that change is really necessary > and increases the resource availability and productivity. My time spent of > documentation is less on working out the intricacies of DocBook and more on > experimenting with GnuCash and exploring the code to ensure I understand > what is going on. DocBook is not my personal limitation although my > understanding of it is far from complete. > > DocBook may not be as compact as asciidoc code but it is well documented and > the tag structure does help in finding and isolating errors. It may be more > productibve to go to DocBook 5 for example and enable a common glossary > between the guide and help manual and facilitate better crosslinking. > > The prettiness of the output may also be addressed by changes to the style > sheets used to process the current docs which would not require a change to > an entire codebase or change of tool chain. > > David Cousens ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All.
Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
The existing tool chain meets more than the need for a single document. There is translation into multiple languages, online versions, standalone pdf, epub etc. The Read theDoc' format is certainly quite nice but to be a replacement candidate for the current tool stream it has to offer considerable advantages over the current process while still meeting those needs. Maybe these can all be met with an alternative but his needs to be ascertained. The current documenters have invested time and effort in coming to grips with what we currently use. Replacing part of the current tool chain means we are going to have to put time and effort into learning a new approach when in most case our available time for working on the documentation is better spent exploring GnuCash and how it works and the underlying code. It is not as though we are particularly well resourced in this area. I support Frank's approach of defining and documenting what it is the documentation currently does and needs to do then looking at what the advantages/disadvantages of any alternative approach to the current tool chain actually are and whether it can mmet all the current needs. In doing this we also need to examine who is currently working on the documentation and how they might react to a significant tool change. If a major effect is we lose a significant part of the current resource base in this area, is it really productive to make a change unless that change is really necessary and increases the resource availability and productivity. My time spent of documentation is less on working out the intricacies of DocBook and more on experimenting with GnuCash and exploring the code to ensure I understand what is going on. DocBook is not my personal limitation although my understanding of it is far from complete. DocBook may not be as compact as asciidoc code but it is well documented and the tag structure does help in finding and isolating errors. It may be more productibve to go to DocBook 5 for example and enable a common glossary between the guide and help manual and facilitate better crosslinking. The prettiness of the output may also be addressed by changes to the style sheets used to process the current docs which would not require a change to an entire codebase or change of tool chain. David Cousens The time spent in reviewing this - David Cousens -- Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-User-f1415819.html ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All.
Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
On Wed, 6 May 2020 at 15:20, Adrien Monteleone wrote: > > Thanks for the bug reference. Certainly, I agree change won’t happen soon, or > easily, nor do I think it should. > > The point of my post was to encourage the OP not to lose hope or give up. > > Regards, > Adrien As someone else who's not often posting, but has been of late, what I'd also say to the OP is: if you now have a process that can take the existing doc sources and render them for display at "Read The Docs" then that's all you need. Just keep on doing it against the existing sources as they get updated. No harm in having multiple renderings, nor multiple tool chains to render the existing sources for as many other renderings as.possible. ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All.
Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
On 5/6/2020 11:15 AM, Adrien Monteleone wrote: > ... I personally would like to see its development move to something with less of a hurdle or learning curve as that could include more seasoned users who aren’t build savvy. - That's certainly one potential benefit. A few comments from https://github.com/Gnucash/gnucash-docs/pull/132 help explain this. The wiki has instructions on the documentation process at https://wiki.gnucash.org/wiki/Documentation_Update_Instructions. It is a fairly sophisticated process that essentially uses a computer programming environment to develop the documentation. It also integrates context-sensitive help into GnuCash but other applications find other ways of doing this. This means the burden of writing the documentation essentially falls to the developers, something they're unlikely to be particularly interested in, taking them off the task of developing the program. Documentation is a specific skill and non-programmers may well do a better job provided they understand the features of the program. ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All.
Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
Thanks for the bug reference. Certainly, I agree change won’t happen soon, or easily, nor do I think it should. The point of my post was to encourage the OP not to lose hope or give up. Regards, Adrien > On May 6, 2020 w19d127, at 1:57 AM, David T. wrote: > > Adrien, > > Given that the dev team has discussed documentation formats since at least > 2013 (cf. https://bugs.gnucash.org/show_bug.cgi?id=722016), I wouldn't expect > a rapid transition to some other format just because someone comes up with a > fancy new tool. > > > David T. ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All.
Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
Adrien, Given that the dev team has discussed documentation formats since at least 2013 (cf. https://bugs.gnucash.org/show_bug.cgi?id=722016), I wouldn't expect a rapid transition to some other format just because someone comes up with a fancy new tool. David T. On 5/6/2020 11:15 AM, Adrien Monteleone wrote: Could be it just hasn’t been seen widely yet. Posts here are odd beasts in that some get lots of activity and others nary a peep. Being that they are mail, this may be a semi-permanent condition for a thread. I’ll hazard a guess that it may have been appealing more for potential documenters than readers, and probably not something a casual user would comment on. If would-be documenters haven’t seen the thread or investigated... Don’t sweat it. I’ll offer the perspective that while I’m not very chatty on this particular topic here on the list at the moment, I initially like the idea and I’ll look more into it for working on the documentation and as a user. But I can’t promise a flurry of testing or commentary on a specific time frame, with my 7000 irons in 30 fires. I’m sure I’m not the only one in that boat, odd as it may seem. I also have some previous GC ‘projects’ I’ve started that I’d like to finish before the 4.0 freeze, though they just involve some research and beta testing mostly. I suspect something major like moving documentation to a new platform won’t happen for 4.0, though that isn’t out of the question. I personally would like to see its development move to something with less of a hurdle or learning curve as that could include more seasoned users who aren’t build savvy. Regards, Adrien On May 6, 2020 w19d127, at 12:11 AM, flywire wrote: I thought there would have been more comments on Porting the Tutorial & Concepts Guide to ReadTheDocs.org tested recently at https://gnucash-docs-rst.readthedocs.io/ ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All. ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All.
Re: [GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
Could be it just hasn’t been seen widely yet. Posts here are odd beasts in that some get lots of activity and others nary a peep. Being that they are mail, this may be a semi-permanent condition for a thread. I’ll hazard a guess that it may have been appealing more for potential documenters than readers, and probably not something a casual user would comment on. If would-be documenters haven’t seen the thread or investigated... Don’t sweat it. I’ll offer the perspective that while I’m not very chatty on this particular topic here on the list at the moment, I initially like the idea and I’ll look more into it for working on the documentation and as a user. But I can’t promise a flurry of testing or commentary on a specific time frame, with my 7000 irons in 30 fires. I’m sure I’m not the only one in that boat, odd as it may seem. I also have some previous GC ‘projects’ I’ve started that I’d like to finish before the 4.0 freeze, though they just involve some research and beta testing mostly. I suspect something major like moving documentation to a new platform won’t happen for 4.0, though that isn’t out of the question. I personally would like to see its development move to something with less of a hurdle or learning curve as that could include more seasoned users who aren’t build savvy. Regards, Adrien > On May 6, 2020 w19d127, at 12:11 AM, flywire wrote: > > I thought there would have been more comments on Porting the Tutorial & > Concepts Guide to ReadTheDocs.org tested recently at > https://gnucash-docs-rst.readthedocs.io/ ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All.
[GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
I thought there would have been more comments on Porting the Tutorial & Concepts Guide to ReadTheDocs.org tested recently at https://gnucash-docs-rst.readthedocs.io/ ___ gnucash-user mailing list gnucash-user@gnucash.org To update your subscription preferences or to unsubscribe: https://lists.gnucash.org/mailman/listinfo/gnucash-user If you are using Nabble or Gmane, please see https://wiki.gnucash.org/wiki/Mailing_Lists for more information. - Please remember to CC this list on all your replies. You can do this by using Reply-To-List or Reply-All.
