Rob Weir wrote:
On Wed, Aug 29, 2012 at 2:40 PM, Keith N. McKenna
<[email protected]> 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
