Keith N. McKenna wrote: <snip> > [knmc] > I will try to put something together over the next few days as far as > constructive feedback > Has been a little more than a few days, but as usual life has intervened. My personal belief is that there was never enough thought put into what the overall documentation needs of the project were. The User Guide was started because many people believed that we absolutely needed to have documentation under the ALV2 license. That necessitated starting from scratch as the User Guides, Admin Guide, etc. where all under either the PDL or CC-BY and could not be used as a basis for this new documentation. I do not believe that it was ever intended to cover all possible documentation needs, nor should it.
That being said I will comment on your points in-line. >>> -----Original Message----- From: Dennis E. Hamilton >>> [mailto:dennis.hamil...@acm.org] Sent: Sunday, July 24, 2016 10:34 >>> To: doc@openoffice.apache.org Subject: [DISCUSS] Places for >>> Installation, Startup, Troubleshooting, Caveats, Tips, Workarounds, >>> and maybe FAQ? >>> >>> >>> I notice that the User Guide draft does not provide connection to >>> topics around installation, startup, and so on, at least not at the >>> top level, >>> <https://wiki.openoffice.org/wiki/Documentation/UserGuide>. >>> [knmc} A link to the HowTo on installation has been added. Start-up should be handled in the same way. As far as "and so on" I cannot comment on that as it is far to vague. [/knmc] >>> The Apache OpenOffice Documentation Project page is project >>> descriptive, rather than documentation descriptive, at >>> <https://wiki.openoffice.org/wiki/Documentation>. This page has a >>> mix of old and somewhat recent material and a variety of formats >>> and works-in-progress. >>> [knmc] As far as I know that was by design. As far as a hodge-podge of material that was also partially by design and partially as a consequence of the documentation team leaving the umbrella of OpenOffice.org and setting up there own site at what is now the ODFAuthors site. [/knmc] >>> I am particularly interested, myself, in information about >>> installation, start up, ways of starting work with documents, >>> saving and locating documents, tips for configuring for careful and >>> systematic operation as well as trouble-shooting, working-around >>> common problems, and limitations to be known about. I am also >>> interested in that information being well-illustrated. My >>> priority, by the way, is Windows first, since that represents over >>> 85% of our user community measured by download statistics. >>> >>> These don't seem to be part of the User Guide project but there are >>> a variety of places where better information could be provided. >>> [knmc] They are not a part of that and it is my opinion that they should not be. They should have there own section of overall documentation. There is a section of the users guide called "cook book" that could be used for some of this type of material. [/knmc] >>> It seems to me that there are three ways to have the supporting >>> documentation address this. >>> >>> 1. Add a section to the user guide for covering Installation, >>> Configuration, Operation, Troubleshooting, and Removal. It would >>> need to deal with separation of the different platforms (and their >>> versions) in some clean way so that users on a particular platform >>> can find what is pertinent to them and requires knowing their >>> computer operating- system when it is not the same for all >>> platforms. It would also need to deal with differences in AOO >>> version functionality/caveats in some manner. >>> [knmc] Again in my opinion those do not belong in a traditional user guide but in a separate set of specialized docs. [/knmc] >>> 2. Use the current structure and update and add the information >>> that seems to be important for providing the kind of documentation >>> support I am speaking of, employing/expanding HOWTOs and the >>> Frequently Asked Questions to tie into such material. >>> For me this makes more sense as it makes use of existing resources. [/knmc] >>> 3. Maybe some combination, although cross-referencing might not >>> serve users well unless it is smooth and frictionless (especially >>> around users not losing their place based on what they are looking >>> into). >>> >>> Down the road, I would think it would be good to move The >>> Documentation Project to a DocumentationProject wiki topic, and >>> have current relevant documentation at the Documentation topic. >>> Older material about unsupported software could move to a separate >>> topic page (PreviousDocumentation ?) and cleaned up, and be >>> accessible from the top-level Documentation topic. >>> [knmc] This is a very good idea. There is to much clutter do to years of neglect. [/knmc] >>> Is there some coordination required about this, so that things >>> don't be left in a broken, disconnected state? I think the >>> material could be migrated in a way that keeps everything connected >>> even as material is morphed into a new structure. >>> [knmc] There is definitely coordination needed. They way links and categories work it can be fairly easy to leave something orphaned. [/knmc] >>> - Dennis >>> >>> PS: I notice there were no responses to this question about how >>> inter- version changes or specific-version items are identified. >>> >>> PPS: Something else that needs to be done is cleanup around what >>> is under PDL and what is not. I would thing that needs to be >>> attended to in separation of Apache Licensed material and anything >>> that must be retained under PDL. >>> [knmc] This is definitely something that is long overdue. However it is not something I am comfortable commenting further on as I have virtually no knowledge in this area. [/knmc] >>>> -----Original Message----- From: Dennis E. Hamilton >>>> [mailto:dennis.hamil...@acm.org] Sent: Sunday, January 31, 2016 >>>> 18:17 To: doc@openoffice.apache.org Subject: [QUESTIONS] Dealing >>>> with AOO Inter-Version Changes >>>> >>>> I notice that there is checking of documentation against current >>>> releases of Apache OpenOffice, although that does not seem to be >>>> reflected in the texts themselves, once User Guide pages are >>> designated >>>> as stable/"published". >>>> >>>> I know there were a couple of behavioral changes in AOO 4.1.2 >>>> although that might not show at the current level of >>>> documentation detail. >>>> >>>> I wonder how changes to AOO that are user-perceived will be >>>> reflected >>> in >>>> the documentation. Is not the older form to be maintained so it >>>> can >>> be >>>> found by someone who is looking at such a version? Also, would >>>> we >>> want >>>> to start marking the first version for which a page or chunk of >>> content >>>> is current? >>>> >>>> Perhaps that is covered somewhere in the documentation guidance. >>>> I would be grateful if someone could point me to where this sort >>>> of change-accounting and feature-progression has been decided. >>>> >>>> - Dennis >>>> >>>> PS: Although these questions struck me about the User Guide, if >>>> you >>> look >>>> at the top-level of the MediaWiki documentation section, there >>>> are >>> many >>>> items that are specific to older versions that are (or may be) >>> obsolete >>>> with respect to newer versions of OpenOffice. >>>> >>>> >>>> >>>> -- Dennis E. Hamilton orc...@apache.org dennis.hamil...@acm.org >>>> +1-206-779-9430 https://keybase.io/orcmid PGP F96E 89FF D456 >>>> 628A X.509 certs used and requested for signed e-mail >>>> >>>> >>>> >>>> --------------------------------------------------------------------- >>>> >>>> > To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org >>>> For additional commands, e-mail: doc-h...@openoffice.apache.org >>> >>> >>> --------------------------------------------------------------------- >>> >>> > To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org >>> For additional commands, e-mail: doc-h...@openoffice.apache.org > >
signature.asc
Description: OpenPGP digital signature
