Product SiteDocumentation Site

Fedora Draft Documentation

Documentation Guide

A how-to guide for creating and maintaining documentation for Fedora

Edition 0.2

Legal Notice

Copyright © 2011 Fedora Project Contributors.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at The original authors of this document, and Red Hat, designate the Fedora Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
For guidelines on the permitted uses of the Fedora trademarks, refer to
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
All other trademarks are the property of their respective owners.
A how-to guide for creating and maintaining documentation for Fedora.

1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. We Need Feedback!
1. Introduction
1.1. Purpose of This Guide
1.2. Tips for Success
1.2.1. Be Bold!
1.2.2. Don't Let the Tools Scare You
1.2.3. There's a Team to Back You Up
1.3. Organization of This Guide
2. Documentation Workflow
2.1. Write First, Format Later
2.2. Formatting in DocBook
2.3. Pushing Strings to Translation
2.4. Pulling Strings from Translation
2.5. Building Documents
2.6. Publishing Documents to the Web
2.7. Building Packages from Documents
2.8. Creating a patch
3. Brief Introduction to DocBook
3.1. Why DocBook?
3.1.1. DocBook as an XML Markup Language
3.1.2. Human-readable Tags
3.1.3. Text-based Format for Easy Revision Control
3.1.4. Separation Between Content and Style
3.1.5. Output in a Variety of Formats
3.2. Parts of a DocBook File
3.2.1. Entities
3.3. Dividing a Document into Multiple Files with XIncludes
3.4. Entities: With Great Power Comes Great Responsibility
4. XML Tools
4.1. XML Concepts
4.2. xmllint
4.3. xsltproc
4.4. xmltidy
5. Publican
5.1. Installing Publican
5.2. Creating a New Document
5.3. Validating XML Code
5.4. Building a Document
5.5. Publishing a Document
5.5.1. Preparing Your System
5.5.2. Publishing a Document on the Web
5.5.3. Removing a Document from the Web
5.5.4. Updating a Document on the Web
5.5.5. Marking a Documentation as Draft
5.6. Building RPM Packages
6. Translations
6.1. Translating Documentation
6.2. Introducing
6.3. Creating an Account on
6.4. Installing the Transifex Client
6.5. Configuring .transifexrc
6.6. Initializing Transifex in Your Git Repository
6.7. Mapping Language Codes
6.8. Editing File Filters
6.9. Updating POT Files
6.10. Pushing and Pulling Translations
6.11. Branching and Updating Translations Before a New Release
6.12. Additional Resources
7. Style Guide
7.1. General tips
7.2. Abbreviations, acronyms, and initialisms
7.3. Pictures and screen captures
7.4. Software
A. Revision History