What could Doc be?

[Rob Weir <ro...@robweir.com>]

Re-titling this thread based on the topic drift.

On Wed, Aug 31, 2011 at 2:14 AM, Jean Weber <je...@gmail.com> wrote:
>
> As I've noted before, tracking down past contributors to get agreement
> on changing the license of existing material would be difficult and in
> some cases impossible. Given that the existing material is the obvious
> place to start when producing user guides updated/amended for AOO,
> then the license of that existing material is relevant. AFAIK, we
> can't just take the material, revise it, and change the license; so
> the books would need to be completely rewritten. IMO that would be
> very impractical, because the available people barely keep up with
> minor updates.
>

How many volunteers do you have working on the documentation now? Or,
more important, how many do you think would show up when we get closer
to a new revision?

On the re-licencing question, what is the difficulty?  Is it a problem
with contacting the content contributors, due to changed email
addresses, etc?  Or are there difficulties determining who exactly
contributed to a given document, or similar pedigree issues?


> BTW, I think the user guides could do with a major overhaul, and if
> enough skilled technical writers turned up to do that job, I would be
> absolutely delighted. Alas, I can't see that happening, so all I can
> see (at least for the next year) is either a minor update to the
> existing books (under a compatible, but non-Apache, license) or... no
> books at all.
>

How many would be enough for a major overhaul?

It looks like you've given a lot of thought into the workflow around
doc productions, using OOo at the core.  This is good.  I know I've
advocated for DITA before, and it does have some nice things about it.
 But I can see the advantages of using our own editors for our own
documentation.

In any case, I'd urge you to think boldly about what we could do.  I
know we don't have the resources currently to do much more, but the
truth is we don't get the resources until we articulate a vision about
what we could do.  If we have a compelling vision, then we can try to
entice volunteers, corporate sponsors of editors, etc.

So if resources were not an issue, what would we do?  What could we
do?  How could a fully resourced doc effort best contribute to the
overall success of the project and our users?

-Rob

Re: What could Doc be?

[Jean Weber <je...@gmail.com>]

On Thu, Sep 1, 2011 at 10:36, Rob Weir <ro...@apache.org> wrote:
> On Wed, Aug 31, 2011 at 6:24 PM, Jean Weber <je...@gmail.com> wrote:
>>
>> Rob,
>> Thanks for the comments and encouraging ideas. Before I can answer the
>> more substantial questions in a useful way, I'll need to do some
>> research and dust off my docs-project-scoping skills from my years at
>> IBM Australia. So for now I'll just respond to this one:
>>
>
> Thanks, but no presentation decks, please!  That is one IBM skill I
> hope to escape by working on open source ;-)
>
> My general view is this:  After 10 years of OpenOffice.org we have
> about as many volunteers as the status quo will ever get us.  If
> someone is really interested and able to contribute to the project,
> they either are doing so already, do doing so for LibreOffice.   This
> is due to the great work OOo did over the years raising awareness of
> the project.
>
> The move to Apache changes things somewhat.  The project is now a
> community-led project, not a corporate-led project.  It now has a
> permissive license.  This changes the equation and could bring in some
> new contributors.   I think this will mainly be new
> corporate-sponsored contributors.  Not exclusively, but the changes
> that the move to Apache will bring  will be particularly attractive to
> such contributors.
>
> If we want to do better than that, then we need to do more then the
> status quo.  We cannot just do the same things and expect better
> results.  We need to do more than just migrate/translate/rehost/move
> OOo to Apache.  We need to up our game.  This requires more
> volunteers, of course.  But the magic is, by expressing a bolder
> vision we can attract the kinds of volunteers that can make this
> happen.
>
> Ask yourself, if you were not already involved, and had a history with
> the project, what would interest a person of your skills in
> volunteering? That's the kind of person we want to attract!
>
> I'm not a documentation expert, but I've noticed some trends:
>
> 1) Moves to using structured formats that allow content to be more
> easily sliced and diced and targeted to different outputs.    DITA is
> one way of doing it, but similar approaches could be based on ODF.
>
> 2) Collaboration with users.  Several companies do this their online
> doc.  Each page allows comments, a thread at the bottom of the page
> for user's to enter additional observations, tips, corrections, etc.
>
> 3) Multi-media.  It is amazing what a 30 second video clip can teach
> you about pivot tables that would take pages of text to explain.
>
> 4) Tightening the bounds between documentation, product help, support
> and training.  That goes back a to 1) above, the structuring of the
> information to make it reusable.
>
> Would things like the above attract more interest?
>
> -Rob
>

I agree with your points above. Indeed, I had been thinking about your
points 2,3,4 before reading your note, so we're certainly thinking
along the same lines, at least at the macro level.

Whether overtly working towards those goals would attract more
interest from appropriately-skilled people, I can't guess. Certainly
(3) would attract people who aren't motivated toward print media.
We've had intermittent interest at OOo over the past few years, but
nothing's ever come of it. I think it was mainly from people who
wanted to do multimedia but didn't really know much about it, and
there was no one to act as a mentor to the others.

I don't know how many people from ODFAuthors will choose to work on
AOOo docs; most of the (fewer than 10) active people (on the
writing/editing side) have moved to LibreOffice for their own use.
I've been encouraging people to sign up to this list, but I don't know
if any of them have (other than the techie or semi-techie types like
TJ). So starting over with a new bunch may be necessary, regardless of
other considerations.

Personally, I am not motivated to actually work on (or even be
actively involved in planning) any of the above, despite my opinion
that all are vitally important to the future of OOo. I am a
book-oriented person and at this particular time in my life I am not
very interested in the amount of effort needed to expand my skill set.
As for planning: it's way too much work that I don't enjoy, and my
approach is "if I'm not having fun, I'm not going to do it". And that,
I'm sorry to say, includes scoping the work (and number of people)
needed for book-like user guides, never mind anything else, beyond
some very high-level estimates.

IMO at least one full-time equivalent person is needed for keeping
each of the existing books up to date and improving them: Getting
Started, Writer Guide, Calc Guide, Impress Guide, Draw Guide. Indexing
is in major need of improvement.

Two items that are conspicuously missing from the present set of user
guides are a Base Guide and a Migration Guide (the latter primarily
for people moving from Microsoft Office).

I've been looking at the Symphony documentation wiki [1] and am
impressed with it as a good example of one important type (subset) of
user documentation: what I would call well-organised and searchable
how-to's. I particularly like the way there is a set of original
non-editable docs and a set of editable docs derived 1-to-1 from the
original docs, each set with clear links to the other. [2] is an
example. As mentioned in your point (2), the pages offer an
opportunity for readers' comments as well as direct editing. This
overall approach seems to me to meet the requirements of both camps
regarding end-user docs: controlled "official" docs, plus an immediate
opportunity for community participation. (I haven't looked around
enough to see how someone might offer a new page of info, not just
respond to existing pages, but I'm sure it's there.)

[1] http://www-10.lotus.com/ldd/lswiki.nsf/xpViewCategories.xsp?lookupName=Lotus%20Symphony%203%20Documentation
[2] http://www-10.lotus.com/ldd/lswiki.nsf/dx/Inserting_an_Entire_Text_Document_ls3

Regards, Jean

Re: What could Doc be?

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

On Fri, Sep 2, 2011 at 8:19 PM, Jean Weber <je...@gmail.com> wrote:
> Returning to a point Rob made earlier...
>
> On Thu, Sep 1, 2011 at 10:36, Rob Weir <ro...@apache.org> wrote:
>> My general view is this:  After 10 years of OpenOffice.org we have
>> about as many volunteers as the status quo will ever get us.  If
>> someone is really interested and able to contribute to the project,
>> they either are doing so already, do doing so for LibreOffice.   This
>> is due to the great work OOo did over the years raising awareness of
>> the project.
>
> New people become available every week, as their "able to contribute"
> status changes. A conspicuous subset of these are people who are
> retiring from paid work (voluntarily or not) and now have time. There
> are other categories, primarily techwriting students and writing or IT
> professionals looking to make a change into techwriting.
>

Good points.  There will always be some degree of turnover, with new
people coming in, and others leaving due to other commitments, etc.
That is natural.  But I was thinking more of a source of net growth.

> The dev@docs.ooo list receives 1 or 2 offers to help per day from
> people not formerly involved with OOo, which I pick up in the
> moderation queue. Of these, very few ever become active or productive,
> but occasionally there is a potential gem: someone with relevant
> skills and/or experience who now has the time to contribute. We have a
> generic "welcome and here's how to get started in OOo Docs" response
> that we send to most such enquiries; at present that suggests people
> join either this list or the ODFAuthors list. If someone sounds
> particularly suitable, I usually contact them with a more personalised
> note.
>

I've seen similar on the dev@ooo list, people stopping in, asking how
they can contribute.  Many of these notes are ignored.  Not knowing
the history of this, I assume that the project was pessimistic that it
could turn new volunteers into productive dev contributors.  I am not
so pessimistic.  That is one reason why I'm encouraging the Linux
build developer education event next week.  Maybe I'll be more
pessimistic after that ;-)

A good question to ask ourselves:  How many new productive coders,
testers, doc writers, etc., have we been able to recruit in the last
12 months?  24 months?  And how did that compare to how things were 5
years ago.   I see many people with 10 or 15 years experience with the
project, but almost no one with 2 or 3 years experience.  That makes
me worry that overall our recruitment has weakened.

> I haven't been paying close attention (sorry), but I am under the
> impression that when the OOo lists are shut down, messages will be
> redirected to this list (with exceptions, such as users@), so this
> list's moderators will be dealing with those from unsubscribed people.
> Are those messages passed through to the list, or sent a reponse of
> some sort?
>

I don't think we've discussed forwarding the mailing lists.  But if we
did do a simple forwardof the traffic, then any posts to those lists
would be held for moderation, unless the poster was also a  subscriber
to this list.  Moderators would then generally let the message
through, assuming it is not spam.


> --Jean
>

Re: What could Doc be?

[Jean Weber <je...@gmail.com>]

Returning to a point Rob made earlier...

On Thu, Sep 1, 2011 at 10:36, Rob Weir <ro...@apache.org> wrote:
> My general view is this:  After 10 years of OpenOffice.org we have
> about as many volunteers as the status quo will ever get us.  If
> someone is really interested and able to contribute to the project,
> they either are doing so already, do doing so for LibreOffice.   This
> is due to the great work OOo did over the years raising awareness of
> the project.

New people become available every week, as their "able to contribute"
status changes. A conspicuous subset of these are people who are
retiring from paid work (voluntarily or not) and now have time. There
are other categories, primarily techwriting students and writing or IT
professionals looking to make a change into techwriting.

The dev@docs.ooo list receives 1 or 2 offers to help per day from
people not formerly involved with OOo, which I pick up in the
moderation queue. Of these, very few ever become active or productive,
but occasionally there is a potential gem: someone with relevant
skills and/or experience who now has the time to contribute. We have a
generic "welcome and here's how to get started in OOo Docs" response
that we send to most such enquiries; at present that suggests people
join either this list or the ODFAuthors list. If someone sounds
particularly suitable, I usually contact them with a more personalised
note.

I haven't been paying close attention (sorry), but I am under the
impression that when the OOo lists are shut down, messages will be
redirected to this list (with exceptions, such as users@), so this
list's moderators will be dealing with those from unsubscribed people.
Are those messages passed through to the list, or sent a reponse of
some sort?

--Jean

Re: What could Doc be?

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

On Wed, Aug 31, 2011 at 6:24 PM, Jean Weber <je...@gmail.com> wrote:
>
> Rob,
> Thanks for the comments and encouraging ideas. Before I can answer the
> more substantial questions in a useful way, I'll need to do some
> research and dust off my docs-project-scoping skills from my years at
> IBM Australia. So for now I'll just respond to this one:
>

Thanks, but no presentation decks, please!  That is one IBM skill I
hope to escape by working on open source ;-)

My general view is this:  After 10 years of OpenOffice.org we have
about as many volunteers as the status quo will ever get us.  If
someone is really interested and able to contribute to the project,
they either are doing so already, do doing so for LibreOffice.   This
is due to the great work OOo did over the years raising awareness of
the project.

The move to Apache changes things somewhat.  The project is now a
community-led project, not a corporate-led project.  It now has a
permissive license.  This changes the equation and could bring in some
new contributors.   I think this will mainly be new
corporate-sponsored contributors.  Not exclusively, but the changes
that the move to Apache will bring  will be particularly attractive to
such contributors.

If we want to do better than that, then we need to do more then the
status quo.  We cannot just do the same things and expect better
results.  We need to do more than just migrate/translate/rehost/move
OOo to Apache.  We need to up our game.  This requires more
volunteers, of course.  But the magic is, by expressing a bolder
vision we can attract the kinds of volunteers that can make this
happen.

Ask yourself, if you were not already involved, and had a history with
the project, what would interest a person of your skills in
volunteering? That's the kind of person we want to attract!

I'm not a documentation expert, but I've noticed some trends:

1) Moves to using structured formats that allow content to be more
easily sliced and diced and targeted to different outputs.    DITA is
one way of doing it, but similar approaches could be based on ODF.

2) Collaboration with users.  Several companies do this their online
doc.  Each page allows comments, a thread at the bottom of the page
for user's to enter additional observations, tips, corrections, etc.

3) Multi-media.  It is amazing what a 30 second video clip can teach
you about pivot tables that would take pages of text to explain.

4) Tightening the bounds between documentation, product help, support
and training.  That goes back a to 1) above, the structuring of the
information to make it reusable.

Would things like the above attract more interest?

-Rob

Fwd: What could Doc be?

[Jean Weber <je...@gmail.com>]

This was supposed to have gone to the list. Sorry for not paying
attention earlier.
--Jean

---------- Forwarded message ----------
From: Jean Weber <je...@gmail.com>
Date: Thu, Sep 1, 2011 at 07:18
Subject: Re: What could Doc be?
To: Rob Weir <ro...@robweir.com>


Rob,
Thanks for the comments and encouraging ideas. Before I can answer the
more substantial questions in a useful way, I'll need to do some
research and dust off my docs-project-scoping skills from my years at
IBM Australia. So for now I'll just respond to this one:

On 01/09/2011, at 3:21, Rob Weir <ro...@robweir.com> wrote:

> On the re-licencing question, what is the difficulty?  Is it a problem
> with contacting the content contributors, due to changed email
> addresses, etc?  Or are there difficulties determining who exactly
> contributed to a given document, or similar pedigree issues?


Tracking people down is the main problem. In some cases we no longer
have even the email address they used when participating, and in other
cases I have attempted several times to reach people (at thair last
known address) but had no response. I believe that at least one
contributor is dead.

We do have a record of who contributed to each chapter (on the copyright page).

--Jean

>
>