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
