Dave Barton wrote:
-------- Original Message --------
From: Keith N. McKenna <keith.mcke...@comcast.net>
To: ooo-dev@incubator.apache.org
Date: Sat, 15 Sep 2012 21:18:34 -0400
Greetings All;
In order to stimulate some discussion on user documentation I have added
the hollowing page to the User Documentation Plan on the Plannig Wiki:
https://cwiki.apache.org/confluence/display/OOOUSERS/User+Guides+Revisted.
It offers 3 scenarios or the creation of the docs. I believe that we can
no longer put this issue aside.
Please take a look at the page and eel free to comment there and on this
list. Also feel free to add to or change any content there.
Regards
Keith N. McKenna
Hi Keith,
This issue was extensively, although inconclusively, discussed last
year. Thank you for revisiting a much neglected aspect of the project.
I tried valiantly to wade through that discussion in the archives. I got
most of it, but it took some pretty convoluted paths with no real
conclusion that I could see. It just sort of died.
In order to avoid confusion I believe we should define "documentation"
in the form that I believe you are referring to. I see this as
documentation made available to end users, separate from, but in sync
with, that which forms part of the released code. (eg. the in-built help
facility.)
You are absolutely correct, that is the exactly the type o documentation
I am referring to. Along with the FAQ's, HowTos and tutorials.
Obviously scenario 1 is not an option, because _good_ end user
documentation is an essential component of post=installation support.
I couldn't agree more.
Scenario 2 under "Cons":
"Licensing issues". We are already hosting the existing "outdated"
guides on Apache servers (eg.
http://wiki.openoffice.org/wiki/Documentation).
My gut says that they were "grandfathered" in with the original grant to
Apache and that attempts to go forward with new docs would meet with
serious push back from many quarters.
"Possible distribution issues". As stated above the type of
"documentation" we are discussing here does not form part of the source
or (convenience) binaries.
Again I foresee potential for serious push back. My admittedly hazy
understanding of Apache policy frowns on pointing users to fairly large
files on Apache controlled servers due to bandwidth and other concerns.
In the event that either of the above were to be a graduation issue
Apache Extras, ODFAuthors, could be options available to us.
I agree.
I do not see Scenario 3 as a viable option. Yes it would give us all a
nice warm fuzzy feeling to say that everything in any way related to AOO
was ALV2 licensed. In reality we would need to recruit a large number of
skilled technical writers, an animal which is extremely rare and
difficult to catch. Even if this were possible, it would be unlikely
that the end result would be very different, albeit more refined, from
what we already have. The ODFAuthors (OOoAuthors) worked on the original
documentation for ~10 years and it is still incomplete.
I share your concerns around option 3, but given that AOO 4.0 has the
potential for substantial UI changes along with enhancements and bug
fixes I believe that it does bare more than cursory consideration.
Even though work on AOO documentation at ODFAuthors virtually stopped
when Jean Hollis Weber resigned from this project, the door remains open
for us to pick up and carry on the work already done there. Now that my
health is returning to something approaching normal, this would be a
good starting point for me to get fully involved.
That was the feeling I got also. I am not a coder, nor am I tech writer.
I am an manufacturing engineer that has some experience in reviewing
technical documentation. This looked to me like the bet way for me to
contribute to a project that I have used the output from for a number of
years.
Hopefully we can quickly come to a consensus and start moving forward on
this.
I whole heatedly second that motion.
Regards
Keith
Regards
Dave
