How to write draft documentation
Revision as of 12:38, 22 February 2009
Here are some tips on writing draft documents for submitting to the DocsProject.
Preferred File Formats
The following file formats are recommended for draft documents, and are easy to work with:
- DocBook XML, using the
example-tutorialtemplate 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.
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:
- Purpose - What the document enables the reader to accomplish
- Audience - The skills and interests of your intended readers
- Additional Resources - relevent
infopages, 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:
- 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.
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
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.