[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Newbie wants to join
Ok everyone,
from what I see, we need two things:
- A documentation environment -----------------------------------------------
tools, presentation (I mean giving a consistent look to the doc), people in
charge (doc admins)
- A documentation methodology -----------------------------------------------
Defining the doc audiences:
====================
I think that dividing the docs into User/Administrator/Developer is a good
idea. I would like to start with the dev doc at the beginning, because that
would allow me to familiarize myself with Ozone. The other docs
(user/admin) would gradually burgeon from the dev doc, retaining and
reformulating for their respective audience.
Defining a doc structure:
==================
Table of contents, Overview, Chapters or Sections on the covered topics,
Conclusion.
Defining the people who take part in the doc process:
=======================================
l propose the following: at least two individuals are involved in writing a
given set of documentation:
- the Editor:
That person's task is to write documentation on a specific topic,
according to the workflow defined further below. The editor is not
necessarily an expert; he will be helped (see 'Mentor' below). But he his
willing to become one, eager to go to the heart of the subject, ask
questions, find answers, search, learn a lot. He is curious, not afraid to
look naive or stupid. In fact, his ignorance will be helpful; after all, he
is writing for people like him, so he understands them and is the best
person to communicate with them. Furthermore, the editor is responsible for
writing clear, concise doc, doing as much as he/she can to make it easy for
the audience to understand (meaning that the editor respects at least
minimal pedagogical principles). The editor is also responsible for
respecting the documentation style (defined as part of the doc
environment), i.e. the 'look' of the doc.
- the Mentor
The mentor is an expert on the subject treated by the editor; he his the
latter's primary resource. The editor asks clear, concise answers to the
mentor, who answers clearly and concisely. The mentor must be patient, for
the editor might seem ignorant at first. That will fade with time; as
mentor and editor collaborate with each other, they gradually find
themselves on the same wave length.
Defining a work flow:
================
- A documentation need is identified by a potential editor
- The potential editor notifies the appropriate people about his intentions
- If justified, the documentation need becomes a Topic as part of the Ozone
Doc Project
- The editor requests for a mentor to volunteer and assist him (there can
be more than one mentor)
- The editor does a first exploration of the Topic; he provides the mentor
with an initial list of questions to help himself start on a good note. The
mentor should in turn of course answer those questions, but also care about
putting the editor on the right track, adding any additional explanation
necessary.
- The editor writes an initial draft and submits it to the mentor
- The mentor corrects/annotates the draft and provides additional
info/warnings if necessary
- The editor proceeds to the corrections
- The result (Topic) is integrated as part of the Ozone Documentation Project.
Of course, the whole process is iterative, meaning that editor/mentor can
go back and forth at any step, until all is clear before proceeding to the
next step.
Yanick