Dennis E. Hamilton wrote: > Thanks for the comments, Keith. > > I only knew that ODFAuthors was already in full operation when the > Apache OpenOffice podling was created. I didn't know what the prior > history with openoffice.org was. > > We shot ourselves in the foot with the ALv2 requirement, especially > since the existing materials had many contributors and at the time > CC-By wasn't thought to be so toxic as it is for releases. We still > have tons of stuff under PDL and it is not thought to be awful. I > think because it does not appear in our source-code releases. > > Life is still intervening. Yes, in print I would put the > installation and trouble-shooting material in the back of the book. > We can do something similar along the lines you align with in the web > context, below. > > A minimum case, probably not well organized, would be enough web > pages and screen captures to back up something like the 4.1.2-patch1 > README, so that people could be shown how to do all of the > prerequisites. Those come in handy for many other cases and it would > be great to have something to link to for situations like the hotfix > and especially things like resetting the user profile, etc. > [knmc] The case of resetting the profile is already handled as part of the FAQ'S <https://wiki.openoffice.org/wiki/Documentation/FAQ/General/Spellchecker_Shows_all_Word_Misspelled> and The HowTo's <https://wiki.openoffice.org/wiki/Documentation/How_Tos/Handling_the_OpenOffice.org_User_Profile#Resetting_the_User_Profile> Though the HowTo article could use some rework, especially the section on resetting the profile.
As far as the hot-fix it should not be to difficult to put something together based on the readme files released as part of the package. [/knmc] > So I guess the first thing would be enough skeleton to hang those > bits onto so that it can have permalinks when referenced outside of > the Wiki. Then it can be updated and filled in. > [knmc] I can do that fairly easily. The question is where do we put it. Should it be in the HowTo's section or in the cookbook section of the User Guide? [/knmc] > > >> -----Original Message----- From: Keith N. McKenna >> [mailto:keith.mcke...@comcast.net] Sent: Sunday, September 4, 2016 >> 19:58 To: doc@openoffice.apache.org Subject: Re: [DISCUSS] Places >> for Installation, Startup, Troubleshooting, Caveats, Tips, >> Workarounds, and maybe FAQ? >> >> 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
