Product SiteDocumentation Site

Fedora Draft Documentation 1

Documentation Guide

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

Edition 1

Legal Notice

Copyright © 2011–2014 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 http://creativecommons.org/licenses/by-sa/3.0/. 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 https://fedoraproject.org/wiki/Legal:Trademark_guidelines.
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.

Abstract

A how-to guide for creating and maintaining documentation for Fedora.
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. We want feedback
1. Introduction
1.1. Purpose of This Guide
1.2. Tips for Success
1.3. Organization of this Guide
2. The Fedora Docs Community
2.1. Getting Started
2.2. Mentors
2.3. Communication
2.4. Office Hours
3. Documentation Workflow
3.1. Write First, Format Later
3.2. Formatting in DocBook
3.3. Pushing Strings to Translation
3.4. Pulling Strings from Translation
3.5. Building Documents
3.6. Publishing Documents to the Web
3.7. Building Packages from Documents
3.8. Creating a patch
4. Brief Introduction to DocBook
4.1. Why DocBook?
4.1.1. DocBook as an XML Markup Language
4.1.2. Human-readable Tags
4.1.3. Text-based Format for Easy Revision Control
4.1.4. Separation Between Content and Style
4.1.5. Output in a Variety of Formats
4.2. Parts of a DocBook File
4.2.1. Entities
4.3. Dividing a Document into Multiple Files with XIncludes
5. XML Tools
5.1. XML Concepts
5.2. xmllint
5.3. xsltproc
5.4. xmltidy
6. Publican
6.1. Installing Publican
6.2. Creating a New Document
6.3. Validating a Document
6.4. Building a Document
6.5. Publishing a Document
6.5.1. Adding a New Document
6.5.2. Updating a Document
6.5.3. Removing a Document
6.6. Packaging a Document
7. Translations
7.1. Translating Documentation
7.2. Introducing Transifex.net
7.3. Creating an Account on Transifex.net
7.4. Installing the Transifex Client
7.5. Configuring .transifexrc
7.6. Initializing Transifex in Your Git Repository
7.7. Mapping Language Codes
7.8. Editing File Filters
7.9. Updating POT Files
7.10. Pushing and Pulling Translations
7.11. Branching and Updating Translations Before a New Release
7.12. Additional Resources
A. Style Guide
A.1. General Guidelines
A.1.1. Composition
A.1.2. Usage
A.1.3. Other Writing Questions
A.2. Content and Rendering
A.3. Dates and Times
A.3.1. Absolute Dates and Times
A.4. Fedora Specific Conventions
A.4.1. Screenshots and Images
A.4.2. General Conventions
A.4.3. DocBook XML
A.4.4. Wiki
A.4.5. ReST
A.4.6. Plain Text
A.4.7. Other Formats
A.5. Common Mistakes
A.5.1. Spelling
A.5.2. Grammar
A.5.3. Punctuation
A.5.4. Constractions
A.6. Word usage, capitalization, and spelling
A.7. Quick Reference
A.7.1. Numbers
A.7.2. Abbreviations
A.7.3. Punctuation
A.7.4. Lists
A.7.5. Titles
A.7.6. Units of Measure
A.7.7. Common Technology Terms
A.7.8. Denoting trademarks
A.8. Resources
A.8.1. Useful FLOSS Project Guides
A.8.2. Other Style Guides
A.8.3. US-English Grammar
A.8.4. Standards
A.8.5. DocBook
A.8.6. Other Resources
B. Revision History
Index