[GNC-dev] Long Term Documentation Directions

[Adrien Monteleone]

David,

Count me in. (with a vote for Markdown)

Consider the idea of making the bulk of the current Help to be appendices of the new Manual. Many of those pages are simply reference lists of the menu entries.

Also, consider arranging the Manual by function rather than form. If GnuCash evolves to more closely follow the Gnome HIG, the UI is going to be very different in how it presents each function and where it appears. Arranging the manual this way will mesh nicely with that path and relieve the need to completely re-write it yet again.

Regards,
Adrien

> On Sep 8, 2018, at 10:48 AM, John Ralls <jralls at ceridwen.us> wrote:
> 
> 
> 
>> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel <gnucash-devel at gnucash.org> wrote:
>> 
>> Hello,
>> 
>> As I have noted in another thread recently, I am finding the process of updating the various documentation pieces extremely challenging—due in large part to the fragmented nature of this documentation. Different contributors have placed information on similar topics in any of a number of official locations in the GnuCash documentation realm, making the update process a circular nightmare. 
>> 
>> This leads to variation in content, approach, and likelihood that a user is going to locate the full information on a given subject.
>> 
>> Rather than tackle each editorial task as if somehow this time it will be different, I would like to ask whether there would be support for a complete rewrite of the documentation. My idea would be to somehow merge all the content from the Guide and the Help into one huge file, and then establish a single Grand Unifying Manual that would provide users with a single source for help. Contextual help would be stripped back to only naming on screen functions, with references back to the GUM in all cases. The wiki would remain primarily for specific use cases and temporary issues. The FAQ would also point to the docs in most cases. Optionally, I would strip out the “Tutorial” aspect of the Tutorial and Concept Guide, as I think a solid Manual would obviate the need for this aspect (that, and the fact that most of the Tutorail sections are written in a “Hi, how are ya” folksie tone that I find inappropriate in formal documentation).
>> 
>> I do not make this suggestion lightly—I know the complexity and difficulty of such an endeavor. However, I increasingly find that the content of the Help and Guide are so inextricably enmeshed that any attempt to clean up one will have extreme impact on the other—and attempting to shepherd these changes through piecemeal is cumbersome at best. 
>> 
>> Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 287. That’s over 500 pages of information—a good portion of which is duplicated across the docs. Any such rewrite would entail a HUGE effort, which is why I write this email: there is no way anyone would undertake this without knowing in advance whether the community would accept such a change at the outset.
> 
> I’ve no objection in principle.  Thorough preparation for such a rewrite would also include a review of the mailing list archives and the wiki.
> 
> We should resolve the source-format question (Docbook/Asciidoc/Docx/Markdown) before beginning actual writing.
> 
> It’s a pretty massive project, I think you’ll need to recruit a team.
> 
> Regards,
> John Ralls
> 
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel