cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From giacomo <>
Subject Re: [vote] Diana Shannon as Documentation Coordinator
Date Tue, 16 Apr 2002 19:08:29 GMT
On Tue, 16 Apr 2002, Diana Shannon wrote:

> > So, Diana, please, introduce yourself and introduce your plan of action
> > (as you did with me privately) so that the rest of the community can
> > vote.
> I've been happily working with Cocoon (1 and 2) for the past eighteen
> months. My clients and I love it. As a user, however, its frustrating to
> be unable to assist in Cocoon's development because I lack the
> high-order architectural understanding and experience to contribute
> code. So, I decided to ask Stefano if the project could use a little
> editing assistance, to help plug some of the holes many new users seem
> to fall through when they read the documentation.
> My background is a mix of programming, design, and educational product
> development. At 39, I'm probably a grandmother compared to the rest of
> you.

Hey, there are some older people like you here, belive me ;)

> I have an engineering degree from Dartmouth College (home of BASIC
> and time-sharing systems). Over the years, I've used lots of different
> programming languages in my work which has focused primarily on
> developing simulation-based training tools. My language of choice over
> the past few years has been Java. I used to provide systems integration
> and consulting services to a number of publishers and presses in the
> States (where I learned/applied all major style/grammar conventions for
> publications). I've also been an author/co-author of a number of
> software- and print-based educational tools, as well as an editor for
> the works for others. So you could say I've experienced first-hand the
> demands and expectations of publishing.
> However, I need to make a small disclaimer. I am not a technical
> document editor/writer by training. I have never served, in a formal
> capacity, as a technical document editor/writer. If someone more
> qualified than I would like to step forward to do this job, I would be
> *more* than willing to step back and assist that person. However, I do
> have a strong background and lengthy experience in writing, editing and
> copy editing, particularly with international teams. Please understand
> that I do have tremendous respect for the current Cocoon docs,
> considering the amazing fact that so many authors are writing in a
> non-native language. I have worked in many non-English environments
> myself (primarily Spanish, French, Russian, and a few others), and know
> how difficult that can be (at least for me). My goal, as an
> editor/coordinator, would be simply to increase the efficiency of
> learning efforts for users and to make a stronger impression on some of
> management types who might be evaluating Cocoon.
> If I were to do this job, here's how I might begin. Please understand I
> wasn't considering this level of commitment when I initially approached
> Stefano. Therefore, I haven't had a lot of time to prepare my thoughts.
> 1. Post a questionnaire to developer and users lists, asking for
> feedback on the shortcomings of existing documentation as well as
> suggestions for new documentation.

Hopefully we get some more precise answers to point us to the
shortcomings than simple stating "Cocoon lacks docs".

> 2. Harvest archives for more feedback on problems/holes/needs. Monitor
> lists for emerging needs, potential contributors, etc.

This is a good point. Usually developers are not very sensible to
monitor questions and fill up the FAQ with it.

> 3. Post to lists a summary of all feedback received.

+1 showing transparency of the coordination work.

> 4. Post to list an outline/action plan/framework proposal to address
> problems. Ask for comments.
> 5. Decide on a plan with a vote.


> 6. Invite contributions of all shapes and sizes from users/developer
> list. Contributions can be rough drafts, outlines, code snippets, etc.

The mailing lists itself contains alot of tips and tricks to be a source
for it but probably you meant this in 1) as well.

> 7. Start editing existing docs. Start authoring new docs.


> 8. Develop style guide and author's tips for all future submissions.

How does the Forrest project play into this?

> 9. Recruit/invite other editors/authors/reviewers to assist with ongoing
> effort


> Down the road, point 9 for me is crucial. I'm probably going to be the
> kind of contributor who can commit in big blocks, not a steady stream. I
> do monitor the lists on a daily basis, though, so this kind of effort
> will complement my existing habits.

Sounds like a good plan to me.


To unsubscribe, e-mail:
For additional commands, email:

View raw message