Hi, Am 08.09.2018 um 17:48 schrieb John Ralls: >> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel >> <[email protected]> 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.
-: I18N: We will loose the current translations and probably frustrate the last translators and loose their readers. ?: Usability: Will F1 or pressing the Help button still deliver the right content? I know it is aslo now not always th case. Historical note: we had a GUM in version 1 and I assume there were reasons to break it in two parts. > 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. You might also consider to choose a more recent license. But that would mean, you must not copy&paste. > Regards, > John Ralls _______________________________________________ gnucash-devel mailing list [email protected] https://lists.gnucash.org/mailman/listinfo/gnucash-devel
