incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jean Weber <jeanwe...@gmail.com>
Subject Re: What could Doc be?
Date Fri, 02 Sep 2011 08:45:33 GMT
On Thu, Sep 1, 2011 at 10:36, Rob Weir <robweir@apache.org> wrote:
> On Wed, Aug 31, 2011 at 6:24 PM, Jean Weber <jeanweber@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

Mime
View raw message