Fedora Documentation Project Quick Start Guide

Note: this document is still in progress. If you have any thoughts, please share them on the fedora-docs-list mailing list.

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

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.

If you choose to be a writer, the follow process must be used:

• Refer to bug fedora-docs-writing to see the list of tutorials already in progress to make sure you do not select a duplicate.

• 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 fedora-docs-writing 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 fedora-docs-ideas for a list of ideas without owners.

  In your Bugzilla report for the new topic, include the following information:

  • What problem it solves
  • Summary of topic
  • Outline for tutorial
  • Intended target audience
  • Whether you are the sole author or whether it is a group effort
  • Whether it helps to create a set of documents with related themes
  • Time estimate on when it will be finished
  • Other resources (other than an editor) you will need to finish -- testers with similar hardware, etc.

• 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.
• Start following the conventions in the guide from the beginning such as preparing your directories according to the example-tutorial.
• Once your file is ready, attach a tarball of the files it to the bug report you created so that an editor can be assigned to it. The editor should be able to untar the file under the fedora-docs CVS module and type make html to build it. If you need help with creating this structure, ask the mailing list for help or ask for an editor so he/she can help you.
• 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 fedora-docs-ready depend on this bug so the project maintainer can review it and post it to the website. Be sure to include the CVS file versions and branch name to make sure the correction document is posted.
• 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.

*Before* the writer hands a document over to the editor, he/she must verify 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 following the naming convention in the Docs Guide
7. Checkout the fedora-docs CVS module if you haven't already, and verify that if you drop in your directory that it builds within the CVS environment, including using a Makefile based on the existing ones.
8. Verify the HTML Output:
   • Click all links to make sure they are valid
   • View each page to make sure there aren't any missing images.
   • Make sure all the images match their description in the text.
   • 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.

Then, the editor is responsible for:

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.

Summary of Tutorial Tracking

Bug fedora-docs-ideas: Docs ideas without owners - a general bucket for ideas for new documents or conversions that come *first* through the list

Bug fedora-docs-writing: Docs in progress - for tracking documents actively being written/developed/edited

Bug fedora-docs-ready Docs ready for going to fedora.redhat.com - when it is done with fedora-docs-writing, it comes here while it undergoes final editing to go to the website.

This means the process of idea -> publication is:

1. File a bug report for your document, or carry the on the one with the idea in it.
2. Move the bug through the tracker in this order

   idea 	             -> 	develop 	        <-> 	publish
   fedora-docs-ideas		fedora-docs-writing		fedora-docs-ready
   

Note: there is a double-arrow between develop <-> publish because a document should stay alive after it is published. Once you have published a version and have moved to writing for the next version of Fedora Core, your document's bug moves back to fedora-docs-writing.