[GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org

[Adrien Monteleone]

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. <sunfish62 at yahoo.com> 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