The Writing Lifecycle for Fedora Docs Project (FDP)

Permission is granted to copy, distribute, and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available at http://www.gnu.org/licenses/fdl.html.

This document may be copied and distributed in any medium, either commercially or noncommercially, provided that the GNU Free Documentation License (FDL), the copyright notices, and the license notice saying the GNU FDL applies to the document are reproduced in all copies, and that you add no other conditions whatsoever to those of the GNU FDL.

Garrett LeSage created the admonition graphics (note, tip, important, caution, and warning). They may be freely redistributed with documentation produced for the Fedora Project.

selinux-faq-1.2-6 (2004-08-11-T16:20-0800)

Red Hat, Red Hat Network, the Red Hat "Shadow Man" logo, RPM, Maximum RPM, the RPM logo, Linux Library, PowerTools, Linux Undercover, RHmember, RHmember More, Rough Cuts, Rawhide and all Red Hat-based trademarks and logos are trademarks or registered trademarks of Red Hat, Inc. in the United States and other countries.

Linux is a registered trademark of Linus Torvalds.

Motif and UNIX are registered trademarks of The Open Group.

Intel and Pentium are registered trademarks of Intel Corporation. Itanium and Celeron are trademarks of Intel Corporation.

AMD, AMD Athlon, AMD Duron, and AMD K6 are trademarks of Advanced Micro Devices, Inc.

Windows is a registered trademark of Microsoft Corporation.

SSH and Secure Shell are trademarks of SSH Communications Security, Inc.

FireWire is a trademark of Apple Computer Corporation.

All other trademarks and copyrights referred to are the property of their respective owners.

Revision History
Revision 0.111 Aug 2004KWade

Initial text version

Revision 0.1.111 Aug 2004DaveP

Initial XML Release

Revision 0.1.216 Aug 2004KWade

XML edits, fixes, formatting, merging ideas with TFox and list.


Table of Contents

Introduction
What to Do First
From Idea to Assignment
You Have An Idea
You Don't Have An Idea
From Assignment to Production
What You Need to Know
What You Need to Do
From Production to Posted
From Posted to Maintained
Maintenance Lifecycle

Introduction

Note

This is a process document, written in a style to describe systems as if they exist. In this document, the reader (you) are treated as someone coming into and through the project as a contributor.

When this process doc describes the system at the level we want to start interacting with it, components can be chunked and parsed to small groups for iteration and contribution.

Ultimately, this process should be a stand alone document or incorporated into the Documentation Guide. Bits that are referenced but remain unwritten are marked (unwritten).

Roles defined in this process:

Author

Authors write content and/or XML; for example, two people can work together, one doing the content, the other converting to XML. An author may also be another technical collaborator who contributes to the document.

Editor

Editors act singularly or together and have go/no-go control over what gets published on http://fedora.redhat.com/docs. The FDP maintainer/leader(s) are de facto members of this group, but do not exert immediate authority. Editors must reach consensus, a majority opinion, or hand over the decision to the editorial board.

Duties of an editor include: helps authors adhere throughout the creation process to the (unwritten) Style Guide.

Editorial board

The editorial board consists of an odd number of members, usually five, and exists to support the editors and the entire project. Usually, several of the board members are also (semi-)active editors. The board takes care of executive editorial decisions involved in overseeing Fedora docs, makes sure we are adhering to our standards, works to ensure the FDP follows and/or advances our process, and so forth. The board is the first arbiter on all decisions about documentation, such as deciding about how to use similar documents in the document set, how to partner and interact with other projects, and so forth.

When the board cannot reach consensus, a vote occurs. If a quorum for voting cannot be achieved that causes a tie, the final decision is up to the FDP project leader/maintainer(s).

QA/Tester

This role does the final check of all incoming files, against a compliance checklist. As the maintainer of fedora-docs in CVS, this role interacts with the overall Fedora CVS maintainer.

Website editor

Maintainer of website, specifically http://fedora.redhat.com/projects/docs and http://fedora.redhat.com/docs.

Fedora Core package maintainer

Future Role: Package maintainer for fedora-docs RPM in Core/Extras.

Workflow editor

This role controls the flow of bugs/requests in bugzilla, as well as making sure workflow is occuring between author-editor teams and on the mailing list.

A single person can fill one or more roles, just as a single role can be fulfilled by one or more persons. For example, with a small size and activity, the project leader can also be the QA/Tester, website editor, package maintainer, and workflow editor. Roles can be taught, shared, rotated, and handled in any matter that the project sees fit.

What to Do First

It is presumed that a writer with a contribution or interest in contributing will do the following:

  1. If you want a fast, Emacs based entry, read the Quick Start...

  2. Read the Documentation Guide (http://fedora.redhat.com/participate/documentation-guide/). Even if you are familiar with DocBook XML, this document contains the markup style details you will need to follow. All final work must be submitted in DocBook XML, although an author can write in a different format and get another author to convert to XML.

    Tip

    Start following the conventions from the Documentation Guide beginning, such as setting up your directory structure and using the Makefile and custom stylesheets. This gets you used to the practice, makes your document easier for others to edit, and saves you time later fixing and changing your XML to match the standards.

  3. Know what documents are in progress; refer to bug 129807 (http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129807) and see the blocking bugs.

  4. Know what ideas don't have authors; refer to bug 129784 (http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129784.)

One thing to do: introduce yourself to the group. Use the self introduction method described at //www.fedora.us/wiki/SelfIntroduction. This is how it is done on fedora-devel-list.

From Idea to Assignment

You Have An Idea

If you have a specific idea in mind, consider your idea in the context of the existing materials. Ask yourself some questions:

  1. Does it build on a previous work?

  2. Does it help create a set of documents with related themes?

  3. Is it a group or solo project? If a group, how can you interest others?

  4. What need does your tutorial fulfill?

  5. Are you willing to maintain this document?

With that in mind, you can bring your idea to the list. Tell us about it, with your answers to the above questions included. Accept some feedback. You want to get to a point where the consensus is, "Yes, that is a good idea, proceed, we'll include it in the Fedora docs repository." Project members will keep in mind your previous posts to the list, other work you've done here and other locations, information from your self-introduction, the quality of your idea, and your level of commitment to it.

Your idea should have the following completed for it:

  1. A scope or charter describing what problem the tutorial solves and how it goes about solving it. This can be a sentence or two.

  2. One or more authors (count yourself).

  3. One or more willing editors/testers (don't count yourself).

  4. A strawman outline and schedule, mainly focusing on milestone generation. Associate them with dates for convenience; the goal is to have a list of milestones which show progress towards completion. While this is optional, it helps coordinate with editors and testers.

  5. All of this is turned into a bugzilla report, either the same one that was started as just an idea (against the idea tracker https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129784) or a new project bug report with Severity: enhancement. The bug should include:

    • What problem it solves, i.e., scope.

    • Summary of the topic of the document, i.e., scope.

    • Intended target audience, i.e., scope

    • Outline for tutorial.

    • Schedule for writing and delivery.

    • List of author(s).

    • Whether it helps to create a set of documents with related themes.

    • Other resources (aside from an editor) you will need to finish the document, such as testers with similar hardware or networks, etc.

You Don't Have An Idea

If you don't have a specific idea for a tutorial in mind, you will need to find an assignment.

  1. There is a list of open assignments at http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129784

  2. Ask on the list or look through existing tutorials, find out if anyone needs assistance authoring or maintaining.

  3. Look around on the Web for useful tutorials written for early versions of Red Hat Linux or other distributions, and consider if they will be useful to port over to Fedora Core. If you find one, go through the process described in the section called “You Have An Idea”

Ultimately, once you do have an idea, you will return to the section called “You Have An Idea” to get the idea accepted for publication.

From Assignment to Production

What You Need to Know

These are items you need to know, guidelines to follow, when writing your tutorial.

  • Read the Style Guide (unwritten). This is a collection of appropriate materials that tell you the style in which you need to write, guide you on grammar, specify word choice, and demystify terminology.

  • Follow the System Documenting Guidelines in the Documentation Guide (unwritten), which specify how to eliminate variables that are not common to a Fedora Core installation. For example, using a default, fresh user account removes dependency on .bash* file tricks. These include best practices for technology usage, such as using rpm packages instead of tarballs. We might choose to have equal preferences for equivalent technologies, such as up2date and yum. Reminder to document the existing system, not provide "fixes" that make a system unsupportable, abnormal, or otherwise _more_ difficult to maintain.

    One of the reasons for using Emacs is that it is capable of indenting the code according to the DTD. It is essential for sane CVS diffs that we all stick to the proper indent formatting. For translation purposes, we may not want to reformat during a translation cycle, as that can throw off the line count for diff tools. Regardless of what tool used to author the XML, it _must_ follow the formatting guidelines defined in the Documentation Guide

  • If you are authoring in XML, prepare your directories according to the example-tutorial and as outlined in the Documentation Guide.

What You Need to Do

Documentation is harder to "release early, release often" than are applications. A broken document can be far more serious than an app segfaulting. However, you don't want to be writing your document in a vacuum, without the benefit of collaborating with peers. It is fine to show it to friends, family, and foes, but it should be noted that it is BETA or DRAFT documentation, and anyone who is fool enough to trust it gets to keep both pieces when it breaks.

You are encouraged to host your work-in-progress (WIP) on a personal webpage, in order to show to project peers. Remember to make the .xml or other source available. If you do not have usable Web space, look for willing hosting partners in the project, who can build and host your beta documents. controversial recommendation? open

If possible, accept patches to your document as XML patches. This makes it easier for peers to offer fixes.

From Production to Posted

At this part of the process, a document has to undergo peer editing, both of content and XML. Posting to the mailing list is the currently accepted process; the editors group may choose to add more process in here.

  1. If you don't have a bugzilla ticket for your document, open one, setting the Severity: to enhancement. Include in this bug the state of the document, the location of the HTML, XML, and PDF if you choose, and all of the other details outlined in the section called “You Have An Idea”. Set the bug to be a dependency on bug # 129807.

  2. Send an email to the mailing list, with the same information as in the bug report, and the bug number. At this time, an editor can step forward or be requested. An editor can also be assigned at the end, if you don't need one while writing.

  3. As early as you are comfortable, get editors engaged in reading the content and XML source. Fix and fight and fix and fight and fix and fight and fix and finally feast. Work well with your editors. Do it publicly. Use the bug report to track changes, discussions, and comments, with URL links back to mailing list threads.

  4. When the document is ready, attach a tarball of the files to your document's bug report and mark the bug QA_READY. If no editor is assigned yet, one will be assigned now.

    The editor should be able to untar the file under the fedora-docs CVS module and type make html to build it. If you ned help with creating this structure, ask the mailing list for help or ask for an editor who can help you.

    Before you hand your document to the editor, you must have done the following:

    1. Spell check all files.

    2. Verify that all URLs are still valid.

    3. Verify that the technical content is correct -- which means follow your own documentation step by step to confirm.

    4. Verify that the names of the files include the language such as example-tutorial-en.xml.

    5. Verify that all sections have an id so all HTML files generated have static filenames.

    6. Verify that all IDs follow the naming convention in the Documentation Guide.

    7. Checkout the fedora-docs CVS module if you haven't already, and verify that if you drop in your directory, it builds within the CVS environment, including using a Makefile based on the existing ones.

    8. Verify the HTML Output:

      1. Click all links to make sure they are valid.

      2. View each page to make sure there aren't any missing images.

      3. Make sure all the images match their description in the text.

      4. Click the Legal Notice link on the title page to make sure it works and contains the FDL, that the version number has been bumped if a previous version existed, and that the last modified date has been updated.

  5. The editor will review your tutorial according to the editing guidelines (which are in progress) and work with you to get them corrected. The editor's responsibilties include:

    1. Making sure the writer followed the docs conventions including using standard ID names, verifying that the parent file follows the example tutorial so that it builds in CVS, and proper use of XML tags.

    2. Checking the grammar and word usage.

    3. Verifying that it is written for the intended target audience.

    4. Looking for any possible missing steps. While reading, if it feels like a step was omitted, ask the writer to make sure. Many times writers who are familiar with a procedure will leave out a step that is obvious to them but not to the reader.

    5. Verifying that it builds in the CVS structure.

    6. Determine if the topic needs a second technical review. If it does, work with the writer to email the mailing lists to find someone to follow the document step by step to make sure it works on their system as well.

  6. When you and the editor(s) have agreed your document is ready for publication, the ticket is set to block bug # 129722 for review before posting to CVS and the website.

  7. At this point, work continues in CVS. If you don't have CVS access, you will need to update the tutorial via patches to the original or new bugzilla reports.

    When CVS write access is available, you may be able to maintain your document directly in CVS. Read about how to use CVS in the Documentation Guide. For more information about Fedora CVS, refer to http://fedora.redhat.com.

An active new document may keep the same ticket open, spawn several sub-tickets and other bug reports blocking the main ticket, and/or be reused for continuous posting. An infrequently changed document can close this ticket and open a new one when new changes are desired.

From Posted to Maintained

Once a document is posted, the lifecycle switches into the maintenance mode.

When there are sufficient documents to make it worthwhile, the Fedora docs project may start maintaining an RPM of documents to ship with Fedora Core, Extras, or another channel (fedora-docs-en-*.rpm). If you or anyone feels your document should be included in that list, it will need a bug report requesting the enhancement, and go through the editors for approval. Once approved, the bug is assigned to the maintainer of the fedora-docs package.

If a translator is interested in translating the document, a request for enhancement bug report should be filed. Similarly, such a translated document can be included in a language specific version of the fedora-docs package.

Maintenance Lifecycle

When a test release is made, that is the time to review your document against the latest reality. If you find a discrepancy or change, you may want to track down the developer and find out how it's likely to end up for final release. Usually you are targeting your update for the release, but there are rare occasions where you update a document for each release, such as the release-notes or a specific FAQ.

When bugs come in against your document, the receiver of bugs to fedora-docs will reassign the bug to you for fixing. Respond in a timely fashion, get clarity from the reporter if needed, and update the document in CVS to reflect the change, noting the bz report number in the CVS changelog. When the bug is ready to close, change to QA_READY (feature unwritten?). An editor will check the change, and if approved, assign the bug to the website maintainer, who will handle the posting to /docs and close the bug.

Note

Don't forget to update the version number of your document when you post a new version. This helps immensely when tracking bugs in bugzilla, where the version number should be specified by the reporter. Remember that you may end up maintaining different documents depending on the version of Fedora Core.

There is likely a reason to maintain an old document for at least one or more versions of FC. A worthy document can be carried on by the Fedora Legacy project, if they see fit, when a version of FC is handed off by the FC developers to the Legacy project. If you do find that it's necessary to maintain multiple versions, you will want to have the CVS branched. File a bug report for that, assigned to the fedora-docs CVS maintainer, who may pass the ticket on to the FC CVS maintainer.

If you come to a time when you realize you no longer want to or are able to maintain your document, you should evaluate if the document deserves to be continued. Either way, announce to the mailing list and specifically the editor(s) about your decision and recommendations about the fate of your document. If possible, look for a person to hand-off maintenance to, and work with him/her/them for as long as possible to do the hand-off. For more details, see the (unwritten) chapter in the Documentation Guide about document hand-off.