openoffice-doc mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Keith N. McKenna" <keith.mcke...@comcast.net>
Subject Re: [DISCUSS] Places for Installation, Startup, Troubleshooting, Caveats, Tips, Workarounds, and maybe FAQ?
Date Mon, 05 Sep 2016 16:22:02 GMT
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.mckenna@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.hamilton@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.hamilton@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 orcmid@apache.org
>>>>>> dennis.hamilton@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-unsubscribe@openoffice.apache.org
>>>>>> For additional commands, e-mail:
>>>>>> doc-help@openoffice.apache.org
>>>>> 
>>>>> 
>>>>> --------------------------------------------------------------------
>>
>>>>> 
-
>>>>> 
>>>>> 
>>> To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
>>>>> For additional commands, e-mail:
>>>>> doc-help@openoffice.apache.org
>>> 
>>> 
>> 
>> 
>> 



Mime
View raw message