[User Documentation]Are there any plans in place or formal user documentation for AOO

["Keith N. McKenna" <ke...@comcast.net>]

Good Day All;

Today I am going to venture into the breach and bring up a topic that in 
my experience is most developers favorite profanity: i.e. User 
Documentation. One of the major reasons I have used and promoted 
OpenOffice.org is its well written and easily available user 
documentation. I see a planning wiki for documentation with no activity 
since 2011.

I also have gone through most of the archived mail to this list I could 
find on this topic with no apparent consensus on what to do. I have also 
tried the ODFAuthors website and mailing list. There appear to be some 
drafts o chapters or a getting started guide but that is about all. The 
response from the list was basically whatever you folks decide to do 
with them.

My basic question is re there any plans for user docs or AOO and if so 
where would the information be found? Although I am not a tech writer 
and have no real experience in the publishing world, this is a area I 
believe that I could be o some small help in. I have done document 
review before on both software documentation and or internal corporate 
standards documents.

Regards
Keith

Re: [User Documentation]Are there any plans in place or formal user documentation for AOO

["Keith N. McKenna" <ke...@comcast.net>]

Rob Weir wrote:
> On Wed, Aug 29, 2012 at 2:40 PM, Keith N. McKenna
> <ke...@comcast.net> wrote:
>> Good Day All;
>>
>> Today I am going to venture into the breach and bring up a topic that in my
>> experience is most developers favorite profanity: i.e. User Documentation.
>> One of the major reasons I have used and promoted OpenOffice.org is its well
>> written and easily available user documentation. I see a planning wiki for
>> documentation with no activity since 2011.
>>
>> I also have gone through most of the archived mail to this list I could find
>> on this topic with no apparent consensus on what to do. I have also tried
>> the ODFAuthors website and mailing list. There appear to be some drafts o
>> chapters or a getting started guide but that is about all. The response from
>> the list was basically whatever you folks decide to do with them.
>>
>> My basic question is re there any plans for user docs or AOO and if so where
>> would the information be found? Although I am not a tech writer and have no
>> real experience in the publishing world, this is a area I believe that I
>> could be o some small help in. I have done document review before on both
>> software documentation and or internal corporate standards documents.
>>
>
> As far as I know, no one is working on documentation, beyond build
> guides and release notes.

I believe that you are correct on that.

>
> If you read through the past discussions you certainly saw that we got
> caught up in license discussions.  The thing that got us stuck before
> was the license on the legacy OpenOffice.org documentation.  It is not
> Apache License or anything compatible.   So if we wanted to revise the
> existing doc we'd need to do it outside of Apache, like with the ODF
> Authors group.  That's were it left off.

Yes I saw the sinkhole the discussion around the license went down. One 
bright spot I did see or a possible compromise was the fact that the 
legacy documents were dual licensed GPL and CC-BY version 3. Looking at 
the website that you referenced for compatible licenses, CC-BY was 
listed, but only as Ver. 2.5. You also noted that it could well be that 
no project had asked about using the version 3. Might it behoove the 
project to ask for a legal ruling on that license?

>
> But it might be a good time to revisit the question.  I think we have
> a greater feel for the nuance about how the ASF thinks about license
> compatibility.  (Or at least I know that there are sufficient nuances
> that one should never say never).

I believe it may well be a good time to revisit. That may we *might*, 
and thatis a big might, have a chance at getting out at least a  getting 
started guide for AOO 3.5.

>
> In one sense this is the lowest of all the low-hanging fruit for
> collaboration between OpenOffice and LibreOffice.  If would be really
> easy to produce a doc set that would be common across the two
> products.  A simple meta-notation could be defined for any
> product-specific concerns.  These could be processed with the Apache
> ODF Toolkit to create the product-specific output docs.
>
> For example:
>
> "Describe core feature here.
>
> %%%IF LibreOffice%%%
> Put LibreOffice specific content here...
> %%%END-IF%%%
>
> Continue with common description"

In theory you are right that it is perfect grounds for collaboration. I 
foresee some interesting discussions developing out of it though.
>
> Moving to DITA for the documentation would be even cleaner, since DITA
> has built-in support for this kind of conditional processing.

There is always the problem training new volunteers, and DITA looks as 
though it might have a fairly steep learning curve.

Keith
>
> Regards,
>
> -Rob
>
>> Regards
>> Keith
>>
>

Re: [User Documentation]Are there any plans in place or formal user documentation for AOO

[Guy Waterval <wa...@gmail.com>]

Hi Rob,

2012/8/29 Rob Weir <ro...@apache.org>

> On Wed, Aug 29, 2012 at 2:40 PM, Keith N. McKenna
> <ke...@comcast.net> wrote:
> > Good Day All;
> >
> > Today I am going to venture into the breach and bring up a topic that in
> my
> > experience is most developers favorite profanity: i.e. User
> Documentation.
> > One of the major reasons I have used and promoted OpenOffice.org is its
> well
> > written and easily available user documentation. I see a planning wiki
> for
> > documentation with no activity since 2011.
> >
> > I also have gone through most of the archived mail to this list I could
> find
> > on this topic with no apparent consensus on what to do. I have also tried
> > the ODFAuthors website and mailing list. There appear to be some drafts o
> > chapters or a getting started guide but that is about all. The response
> from
> > the list was basically whatever you folks decide to do with them.
> >
> > My basic question is re there any plans for user docs or AOO and if so
> where
> > would the information be found? Although I am not a tech writer and have
> no
> > real experience in the publishing world, this is a area I believe that I
> > could be o some small help in. I have done document review before on both
> > software documentation and or internal corporate standards documents.
> >
>
> [...]
>
> Moving to DITA for the documentation would be even cleaner, since DITA
> has built-in support for this kind of conditional processing.
>

Don't take it bad, but such a solution brings also a lot of difficulties.
- How many people are actually able to work with this format?
- How many volunteers could be ready to learn it before producing something?
- How many people are ready to coach the newbies who are learning to work
with DITA? I had a look on it, it's not so easy and I doubt it's possible
to learn it without a little external coaching.
It could be perhaps a good solution in the long term, but also a serious
barrier before producing the first line of documentation, and you have to
repeat all this learning phase with all the new volunteers in the future ...
Only my point of vue.

A+
-- 
gw

Re: [User Documentation]Are there any plans in place or formal user documentation for AOO

[Rob Weir <ro...@apache.org>]

On Wed, Aug 29, 2012 at 2:40 PM, Keith N. McKenna
<ke...@comcast.net> wrote:
> Good Day All;
>
> Today I am going to venture into the breach and bring up a topic that in my
> experience is most developers favorite profanity: i.e. User Documentation.
> One of the major reasons I have used and promoted OpenOffice.org is its well
> written and easily available user documentation. I see a planning wiki for
> documentation with no activity since 2011.
>
> I also have gone through most of the archived mail to this list I could find
> on this topic with no apparent consensus on what to do. I have also tried
> the ODFAuthors website and mailing list. There appear to be some drafts o
> chapters or a getting started guide but that is about all. The response from
> the list was basically whatever you folks decide to do with them.
>
> My basic question is re there any plans for user docs or AOO and if so where
> would the information be found? Although I am not a tech writer and have no
> real experience in the publishing world, this is a area I believe that I
> could be o some small help in. I have done document review before on both
> software documentation and or internal corporate standards documents.
>

As far as I know, no one is working on documentation, beyond build
guides and release notes.

If you read through the past discussions you certainly saw that we got
caught up in license discussions.  The thing that got us stuck before
was the license on the legacy OpenOffice.org documentation.  It is not
Apache License or anything compatible.   So if we wanted to revise the
existing doc we'd need to do it outside of Apache, like with the ODF
Authors group.  That's were it left off.

But it might be a good time to revisit the question.  I think we have
a greater feel for the nuance about how the ASF thinks about license
compatibility.  (Or at least I know that there are sufficient nuances
that one should never say never).

In one sense this is the lowest of all the low-hanging fruit for
collaboration between OpenOffice and LibreOffice.  If would be really
easy to produce a doc set that would be common across the two
products.  A simple meta-notation could be defined for any
product-specific concerns.  These could be processed with the Apache
ODF Toolkit to create the product-specific output docs.

For example:

"Describe core feature here.

%%%IF LibreOffice%%%
Put LibreOffice specific content here...
%%%END-IF%%%

Continue with common description"

Moving to DITA for the documentation would be even cleaner, since DITA
has built-in support for this kind of conditional processing.

Regards,

-Rob

> Regards
> Keith
>

Re: [User Documentation]Are there any plans in place or formal user documentation for AOO

[Andrew Rist <an...@oracle.com>]

I think the best long term resolution is to have a full set of ALv2 
licensed user documentation.  Unfortunately, the path from here to there 
is rather complex, due to the licensing of the current documentation, 
and the lack of interest in moving that direction by the existing 
documentation community.
This is stated to define the current situation, not touch on motivations 
or loyalties.  The ODFAuthors crew has a long history with OOo and now 
AOO and have no interest in abandoning their current content.  They also 
value their autonomy and are comfortable working as ODFAuthors on 
multiple derivations of the OpenOffice code.
That said, it would be very good for the project to have a full set of 
atomic content (individual topics) under ALv2 that can collected into 
different deliverables (help, user manual, quick start guide, tutorials, 
etc).
Beginning this effort, and looking to integrate content from Symphony, 
would be a big step forward for AOO.
Andrew



On 8/29/2012 11:40 AM, Keith N. McKenna wrote:
> Good Day All;
>
> Today I am going to venture into the breach and bring up a topic that 
> in my experience is most developers favorite profanity: i.e. User 
> Documentation. One of the major reasons I have used and promoted 
> OpenOffice.org is its well written and easily available user 
> documentation. I see a planning wiki for documentation with no 
> activity since 2011.
>
> I also have gone through most of the archived mail to this list I 
> could find on this topic with no apparent consensus on what to do. I 
> have also tried the ODFAuthors website and mailing list. There appear 
> to be some drafts o chapters or a getting started guide but that is 
> about all. The response from the list was basically whatever you folks 
> decide to do with them.
>
> My basic question is re there any plans for user docs or AOO and if so 
> where would the information be found? Although I am not a tech writer 
> and have no real experience in the publishing world, this is a area I 
> believe that I could be o some small help in. I have done document 
> review before on both software documentation and or internal corporate 
> standards documents.
>
> Regards
> Keith
>