more defined process

[Karsten Wade]

On Fri, 2004-08-13 at 10:02, Tammy Fox wrote:
> I still haven't finished reading the mailing list since I started my
> maternity leave, so forgive me if this has already been discussed.

Most of the good stuff has been in the last month or so. :)

> I am putting together a Quick Guide for this interested in learning how
> to participate since I get emails daily asking. It also helps define the
> life cycle of a tutorial.

This is a good idea, a gap that needs filling.  Mark Johnson is also
starting work on something with a name like Quick Start Guide, but it
has a different scope.  The purpose is to get people who know the tools
involved a way to get quickly started, a sort of distillation of the Doc
Guide.

Just bringing that up because the titles are similar, but the purposes
are not, and there is room for both.  Just not with the same title. :)

I'll leave the rest of this intact so as to make my inline comments make
more sense:

> Fedora Documentation Project Quick Start Guide
> 
> Since reading the Documentation Guide can be a bit overwhelming at
> first, read this page first to understand how to start participating and
> the process used to add a tutorial to the project.
> 
> The first step is to choose whether you want to be a writer or an
> editor. Refer to the project page for each role's definition (which is
> still being developed). Editors must first be approved by the project
> leader and must have experience with DocBook XML and the proper use of
> tags since all editors must follow the same guidelines when reviewing
> tutorials.

I think a person can fill both roles, depending on what he or she is
doing.  Unless there is a compelling reason not to, I'd suggest
mentioning that you can fill both roles, but it's easier to fill just
one to start.

> If you are chosen as an editor, your name is added to the project page,
> and your job is to wait until writers are finished writing the tutorials
> and need editing.

Just a note, the 'process for choosing an editor' remains unwritten. 
The criteria are pretty obvious.  This could be a job for the editorial
board, to recommend and/or approve editors?

> If you choose to be a writer, the follow process must be used:
> 
> * Refer to bug 129807 to see the list of tutorials already in progress
> to make sure you do not select a duplicate.

A direct link to the dependency tree might make it easy for people to
see what is there:

https://bugzilla.redhat.com/bugzilla/showdependencytree.cgi?id=129807

> * If you have an idea that is not in the list of docs in progress, open
> a Bugzilla report with your idea and be sure to make bug 129807 depend
> on it. Also, email the mailing list to let everyone know you are working
> on it. If you can't think of an idea, refer to 129784 for a list of
> ideas without owners.
> 
> * If you are not familiar with DocBook XML, read the Documentation Guide
> to learn how to use this format. Tutorials must be submitted in this
> format. Even if you are familiar with it, read the guide to learn how
> tags are used for the project and to learn how to setup your file to
> make it compatible with the CVS structure and the common entities file.
> Once your file is ready, attach it to the bug report you created so that
> an editor can be assigned to it.

One thing that has been discussed a number of times over the last few
months is the barrier to entry that DocBook XML provides for some
people.

Without rehashing the arguments, I think the consensus boils down to
this:

* For now, we will take initial submissions in other formats and
volunteers will do the conversion to DocBook.  This is on a case-by-case
basis.

* If the document is going to be maintained, and you are the maintainer,
you must be willing to learn enough DocBook to maintain your document.

* Alternately, you can have a team of authors, where at least one is
responsible for the DocBook.  If you have an idea, bring it to the list
and ask for a co-author who can help you get through the changes.

My suspicion is that 50% of the non-DocBook people who go down this path
end up learning the new format.  These are an unknown number who
wouldn't have come over here in the first place, if they had to learn
DocBook just to get their document into the project.

> * The editor will review your tutorial according to the editing
> guidelines (which are in progress) and work with you to get them
> corrected.
> 
> * Once the writer and editor feel it is ready to be published to the
> website, make bug 129722 depend on this bug so the project maintainer
> can review it and post it to the website.
> Once it is posted to the website, you are still responsible for
> maintaining your tutorial. Until write access is available for CVS,
> submit updates to your tutorial in the form of patches via Bugzilla so
> that they can be applied.

Looks good, very complete and brief.  Only thing we might want is to
point people at a how-to use bugzilla, or do a quick one ourselves that
defines just how to use it for the FDP.

- Karsten
-- 
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41