How to write draft documentation

Here are some tips on writing draft documents for submitting to the DocsProject.

The WritingUsingTheWiki page explains how to contribute to the documents in progress .

Contents:

Preferred File Formats

The following file formats are recommended for draft documents, and are easy to work with:

• DocBook XML, using the example-tutorial template in the Documentation Project CVS
• Plain text
• OpenOffice.org Writer files, saved as the DocBook format (see this page for more information on using Writer)
• The Wiki, using Category:Draft documentation. Read DocsProject/WritingUsingTheWiki for information on how to write so that your document can be converted to DocBook XML.

Use the format and tools that you find most comfortable.

Refer to the Documentation Guide for more information on working with XML DocBook and CVS.

Document Structure

If you choose to write your draft in DocBook, use the example-tutorial from CVS as a starting point.

Each tutorial should begin with an Introduction, with the following sections:

• Introduction
• Purpose - What the document enables the reader to accomplish
• Audience - The skills and interests of your intended readers
• Additional Resources - relevent man and info pages, related documentation included in /usr/share/doc/ on Fedora systems, and public Websites

Including these sections in your draft also helps other members of the Project to provide more relevent feedback.

The second section of your draft should include brief sections explaining any technical concepts that you will use throughout the document. For example, the Managing Software with Yum tutorial has the following Concepts section:

• Concepts
• About Packages
• About Repositories
• About Dependencies
• Understanding Package Names

Establishing the technical concepts at the start of the document enables you to focus the rest of the document on the tasks that the reader may wish to accomplish. Reuse relevent "About" sections from published Fedora documents if they exist - this is perfectly acceptable, and saves you uneccessary work.

The remainder of the sections are the body of the tutorial. Fedora documents are task-orientated, so each section should focus on a particular type of activity or task.

Please include your name, e-mail address, and the date on plain-text and Writer files.
The example-tutorial DocBook template has sections for these details in the document header.

Writing Style

There is an in-progress set of rules available on the Wiki at DocsProject/StyleGuide .

In addition, make sure you have read and understood the short sections on fundamentals of technical documentation and composition in the Documentation Guide. Editors can help you with this, but the process moves faster if you can follow these guidelines.

Submitting Your Draft

Please do not send e-mail attachments directly to the mailing list.

Once you would like to submit your document for peer review, send an e-mail to the documentation mailing list with the subject line "Request for Review: " and the title of your document.

The text of the e-mail should include a link to an on-line copy of your draft. If you are also able to provide an on-line HTML version, please do so, as this results in more list members reading and commenting.

If your draft document is larger than 1 MB in size, specify the size, as a courtesy to users on dial-up and other low-bandwidth connections.