incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Keith N. McKenna" <>
Subject Re: [User Documentation]Are there any plans in place or formal user documentation for AOO
Date Wed, 29 Aug 2012 22:47:12 GMT
Rob Weir wrote:
> On Wed, Aug 29, 2012 at 2:40 PM, 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 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 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.

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

View raw message