Mailing-List: contact doc-help@openoffice.apache.org; run by ezmlm
Precedence: bulk
Reply-To: doc@openoffice.apache.org
Received-SPF: pass (athena.apache.org: domain of gcaod-doc@m.gmane.org
 designates 80.91.229.3 as permitted sender)
To: doc@openoffice.apache.org
From: "Keith N. McKenna" <keith.mckenna@comcast.net>
Subject: Re: Is it time to re-evaluate the viability of internal
 documentation?
Date: Tue, 18 Mar 2014 22:46:38 -0400
Lines: 171
Message-ID: <lgb0jh$gb9$1@ger.gmane.org>
References: <lg8igb$9mm$1@ger.gmane.org>
 <CAP-ksoiZS=C5C7ghQzQEsJYMaTWnceWOp4ojwLJhUAnq-8W2Xg__43876.2685088024$1395151012$gmane$org@mail.gmail.com>
Mime-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha1;
 protocol="application/pgp-signature";
 boundary="5OswVEnqTHqcU08IujA1IIt0NXwO5wjpK"
User-Agent: Mozilla/5.0 (Windows NT 5.1;
 rv:24.0) Gecko/20100101 Thunderbird/24.3.0
In-Reply-To: 
 <CAP-ksoiZS=C5C7ghQzQEsJYMaTWnceWOp4ojwLJhUAnq-8W2Xg__43876.2685088024$1395151012$gmane$org@mail.gmail.com>

--5OswVEnqTHqcU08IujA1IIt0NXwO5wjpK
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Rob Weir wrote:
> On Tue, Mar 18, 2014 at 12:34 AM, Keith N. McKenna
> <keith.mckenna@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 abou=
t
>> 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 mento=
r
>> volunteers who want to help but have not done this type of writing bef=
ore.
>>
>> I would pose a number of questions that should be considered and answe=
red.
>>
>> 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.
>>
>=20
> 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.
>=20
> 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.
>=20
> So what is common between QA and Translation?
>=20
> 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".
>=20
This is a problem in that there are no experienced tech writers active
to give that type of structure and mentoring to volunteers. I do the
best I can, but like you I am not a documentation expert but an engineer
that has done some tech writing along the way.

> 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.
>=20
This is also true with documentation. There are a number of tasks that
can be performed in an hour or possibly even less. One difference with
translation is that that are a number of tasks that are needed that are
only tangentially related to writing such as screen shots and comparing
written documentation to the software. It can keep things from getting
boring, but at the same time requires more skills than just writing or
grammar.

> 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.
>=20
This is something that documentation currently lacks. There will often
be a certain lag between release of the software to release of the
documentation depending on how much writing and checking can be done
with developer builds and beta releases.

> 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.
>=20
This is a something we have been missing. We do have a status page, but
it depends on people remembering to use it and the dialog on the mailing
list has been less than what it should be for good communication. Couple
this with the need for a writer to have a good working knowledge of the
the part that they are documenting can limit the number of people that
can jump in and take over.

> 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.
>=20
> 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.
>=20
3 could be be a part of the problem. There is a disconnect from the
release schedule of the actual software.

> How are with 4)?   Could this be a factor?
>=20
Four is definitely a factor.
> Any other factors?
>=20
Another factor is the lack of infrastructure. Things like a style guide,
writers guide etc. These are documents that experienced technical
writers would do to be used by volunteers to help them learn what needs
to be done.

> 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?
>=20
I am no expert either, just someone that believes that users deserve
quality documentation to use the software. I do not know what is best
either. A survey may help to shed some light on what users want and can
point us in some better directions to recruit the types of people to
push this effort forward.

Keith
> Regards,
>=20
> -Rob
>=20
>=20
>> Regards
>> Keith
>>


--5OswVEnqTHqcU08IujA1IIt0NXwO5wjpK
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (MingW32)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJTKQW+AAoJEH0fu5UhGmBCRKgIAIt2TTh3KVNRAp4MMTuLuqeo
5SFoSHHa2MAFLOkCkZM22Vc3ABUimO7A3TmQH4a9qqpZ1euad1eNzEtaapp1xNcb
uBcN9N83L9NS1WkLW/47ScE6S3YuFaRQBD7Qi95KuLkeyJXOYpQj4FdOm9nm/CjF
DVzgjdOad+ktBrw8hVanbcVHsdQi6kf0pHbTqmns2d8bFC0YaaK8Oj3KGmblXYy3
U9q557EvcKAeLrrCrNVyto/Nq3IYZftDUoKfAyuEHYUvk9lKnNbFrRPKD/gZY1vO
ZQwCf0FQ+rWn0vPy7v7eQZKpOmcEdMcu6Gkw7rvHKZWcjnajf02EDFOcBfAkwlU=
=ohdJ
-----END PGP SIGNATURE-----

--5OswVEnqTHqcU08IujA1IIt0NXwO5wjpK--