RE: [DISCUSS] Places for Installation, Startup, Troubleshooting, Caveats, Tips, Workarounds, and maybe FAQ?

[Dennis E. Hamilton]

Still ...
> [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).]

Of course, I could simply be over-thinking this whole thing and it would be 
more valuable to do something.

I still would like any feedback that there is before investing in something 
like this.

The need for development of hotfix procedures for end-users led me to elevate 
this lingering topic of mine for discussion.  I regret not anticipating the 
need for better information for situations like that and user trouble-shooting 
as well.

 - Dennis

> -Original Message-
> From: Dennis E. Hamilton [mailto:dennis.hamil...@acm.org]
> Sent: Sunday, July 24, 2016 10:34
> To: d...@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>.
> 
> 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.
> 
> 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.
> 
> 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.
> 
>  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.
> 
>  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.
> 
>  - 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: d...@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

[DISCUSS] Places for Installation, Startup, Troubleshooting, Caveats, Tips, Workarounds, and maybe FAQ?

[Dennis E. Hamilton]

[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, 
.

The Apache OpenOffice Documentation Project page is project descriptive, rather 
than documentation descriptive, 
at .  This page has a mix of 
old and somewhat recent material and a variety of formats and 
works-in-progress.  

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.

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.

 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.

 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.

 - 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: d...@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
> 
> 
> 
>