[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, 

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 
- 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.