cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject Re: [vote] Diana Shannon as Documentation Coordinator
Date Tue, 16 Apr 2002 15:24:28 GMT

> 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. 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.
2. Harvest archives for more feedback on problems/holes/needs. Monitor 
lists for emerging needs, potential contributors, etc.
3. Post to lists a summary of all feedback received.
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.
7. Start editing existing docs. Start authoring new docs.
8. Develop style guide and author's tips for all future submissions.
9. Recruit/invite other editors/authors/reviewers to assist with ongoing 

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.

Thanks for your consideration. Please let me know if you need any 
additional information.

Diana Shannon
TerraCare Software

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

View raw message