Dennis E. Hamilton wrote: > [BCC to dev and users lists - please keep the conversation on doc@ > for now, at least by BCC, since it pertains to use of the wiki(s).] > > 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] Much of the skeletal work was done by RGB so I am not completely sure why. He may have envisioned it as part of the "cookbook" section.
> 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] This should not be surprising since like the code base itself it has morphed over 15+ years. Plus the fact that when the OOo Authors group was formed much of the information was moved to there website and was not updated on the wiki. > 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. > [knmc] All worthy goals, but I am not convinced that they all belong in a traditional User Guide. Much (though not all) of the information of that type is available in the FAQ's and the How To's sections of the wiki. As far as concentrating on Windows for the basic User Guide I feel that it is short sighted. > 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] Much of that information does not belong in a traditional User Guide which is what the main focus was meant to be. > 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] Much of this already exists. For instance Configuration: if you follow the links starting with General Options you will find a description of all of the options to configure the program. Also the structure was meant to go from general information relevant to all components to very specific to a particular component. Therefore if an option is different for example in Writer than for the others there should be a link to a more detailed description in the Writer Guide. > > 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. > [knmc] That gets into your PPS around license clean-up. Most of the FAQ'S and HOWTOs' are tagged with the pdl License category. > 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. > > 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 and will require help from people with a much greater knowledge of administration of a mediawiki site than I have. > - 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. > >> -----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". >> [knmc] That is tracked in the Status Document for know. How version changes are to be handled was discussed initially on the doc mailing list but no firm decision was ever made and still needs to be addressed. >> 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
signature.asc
Description: OpenPGP digital signature
