> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel > <gnucash-devel@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@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
