Op zaterdag 8 september 2018 16:57:52 CEST schreef David T. via gnucash-devel: > 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). > The primary reasons I see for merging the documents are - easier for the user - there's only one entry point instead of two - easier for cross linking. In theory you can link across documents but that will only work in well-defined conditions. Links in pdf for example won't link to another pdf document.
So yes, I see value in merging the documents into one. Here's my feedback on your proposal: * Your remark about the "Hi, how are ya" folksie tone brings up an interesting question: how do you envision the manual being written ? Is it just the tone that's bothering you ? Or the whole idea of use-case driven documentation ? I think this is an important point to clear out. * Thinking a bit more on the duplication issue, I think we should distinguish between duplication in the documentation sources and duplication in the end- user result. Duplication in the sources are always a waste of time and a maintenance nightmare. These should clearly be avoided. However in use-case driven documentation duplication can be ok. Use case driven documentation consists of recipes. Several steps in such recipes are shared across many recipes. They can be written once and then reused several times. Can docbook or any of the other suggested formats handle such "snippets" ? * re-reading the proposal it looks like you still suggest to keep two documents: one interface help, the fully stripped down document only listing all buttons/menus and one with all formal documentation. That of course means the linking challenge remains. * other than that I follow your scope assignments: manual for full documentation, wiki for specific (primarily temporary) use-cases, the FAQ primarily a list of pointers to the proper documentation. * and as John suggested: it's best to rally a team for this huge effort. I'll comment separately on the translation challenge. Geert _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
