[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
FW: Re: Newbie wants to join
This got lost somehow, forwarding it again:
-----Original Message-----
From: Per Nyfelt [mailto:per.nyfelt@nordicwave.com]
Sent: den 25 maj 2001 13:58
To: ozone-dev@ozone-db.org
Subject: Re: Newbie wants to join
Moved the documentation discussion from user to dev.
----- Original Message -----
From: "yduchesne" <yduchesne@newtradetech.com>
To: <ozone-users@ozone-db.org>
Sent: Thursday, May 24, 2001 5:21 PM
Subject: 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)
I do not think we need people in charge, just people who takes on the
responsibility of making sure something good comes out of the effort. "In
charge" has a connotation of hierarchy to me but as long as that is not
intended I'm fine with whatever you want to call it.
>
> - 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.
Sound good. Since Eric volunteered to focus on the user doco i think that
would be a good start. I'll start with converting our current documentation
into the new format and try to fit the various pieces into the new emerging
structure.
>
> 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.
>
I do not think there is a need for both existing to write good docs
(although someone has to write it :) the Mentor side could be more loose).
If we post questions on dev or user depending on the nature of the question
we will have a bigger audience and it will probably spawn off some
interesting discussions as we go along. I think most important is to
actively invite and get more people to help out and contribute - not many
think writing documentation is fun so we who do need to put things together
into a coherent piece but there are plenty of very good developers out here
who will not mind answering a question or two if posted on this list - lets
take advantage of that.
> 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.
Sound a bit too formal and linear to me. I fear that it would be difficult
to get an avalanche effect and instead the effort would die out after the
initial burst is over. I'd say if someone is interested in writing an
introduction or howto on a subject he should be encouraged to do so and we
should also put up a list of areas (chapters if you will) that needs to be
covered so that anyone who is interested in helping out easily can find
something to do. As soon as there is a draft in CVS or sent to this list by
the first initiator of the doc, development starts and the ownership is
collective and should be read, commented on and changed by more than one
person.
My 2 cents...
Regards,
Per