more defined process

Sat Aug 14 00:00:03 UTC 2004

On Fri, 2004-08-13 at 16:12, Karsten Wade wrote:
> 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. :)
> 

Mark, if you are on this list, can you add a Bugzilla entry for it and
link it to the tracker for docs in progress? That way, no one else will
start working on the same thing.

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

True. A person just can't be both the writer and the editor on the same
document.

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

I have found that once someone sees their own document in DocBook it
helps them learn it themselves.

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

Yes. How to use Bugzilla specifically for the Fedora docs would make a
great addition.

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

Tammy