Re: Is it time to re-evaluate the viability of internal documentation?

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

On Tue, Mar 18, 2014 at 12:34 AM, Keith N. McKenna
<ke...@comcast.net> wrote:
> Greetings All;
>
> With the documentation list active for over a year now I believe it is
> time to re-evaluate where we are with the documentation effort and if it
> is worth continuing.
>
> My personal perspective is that very little progress has been made nor
> do I see the likelihood of that changing in the near future. It has
> become very frustrating answering inquiries with detailed e-mails about
> what the needs are and where current information is being worked and
> then never hearing from many people again.
>
> We seem not to have been able to attract skilled technical writers who
> can give of there time to drive the infrastructure needed and to mentor
> volunteers who want to help but have not done this type of writing before.
>
> I would pose a number of questions that should be considered and answered.
>
> 1: Is there a need for user documentation?
> 2: Is this the place for that documentation to come from?
>
> I firmly believe that there is a need for high quality user oriented
> documentation for OpenOffice. I am just not sure of the best way to go
> about filling that need.
>
> I hope that this effort can generate a renewed interest in how to go
> about giving the users of this wonderful software documentation of the
> same quality and professionalism as the code base itself.
>

I think it could be interesting to look at two other areas of the
project where we have had greater success with integrating new
volunteers.  Maybe there are lessons there.  I'm thinking of QA and
Translation volunteers.

In those two cases we also get many emails from volunteers offering to
help.  I'm not sure of the exact percentage of those who stick around
longer term.  Certainly we see many express some interest, but then
are never heard of again.  But we also see solid contributors who
anchor the effort, become committers, etc.

So what is common between QA and Translation?

1) The presence of more experienced volunteers to structure the work,
break it into smaller pieces, help new volunteers get started, etc.
You see, for example with QA, Yuzhen taking the lead on defining test
cases, Rainer taking the lead in how use Bugzilla effectively, Juergen
and Andrea reminding translation volunteers of deadlines and helping
them get started, etc.   This is partially a question of "critical
mass".

2) The work is naturally "bite sized".  You can be an effective QA
volunteer working 1 hour a week or 40 hours a week.  There are tasks
of every size.  Ditto for Translators.

3) Both QA and Translation have deadlines, based on our release
schedule, to motivate progress.   Although we're volunteers, the fact
that these efforts are tied to a specific release gives some urgency
to get the tasks done.

4) Both areas have a solid way of tracking progress toward release
goals, with the easy ability for one volunteer to step and finish a
task that someone else has started.  So we're rarely stuck waiting for
a specific volunteer who might not be available at a given time.

So how is it with Doc?   You've done much if 1) above.  I know you've
personally done a lot to make this happen.  2) as well.

I wonder if 3) could be part of the issue?  Doc is not aligned with a
release schedule, at least not in the same way that QA and Translation
are.

How are with 4)?   Could this be a factor?

Any other factors?

I do think documentation is important to users.  But I don't claim to
be an expert in this area, or to know exactly what kind of
documentation they need most, tutorials versus reference material,
PDF's versus videos, etc.  Maybe this could be the subject of a
survey?

Regards,

-Rob


> Regards
> Keith
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org