# Documentation Guide {#idp5111424}
## A how-to guide for creating and maintaining documentation for Fedora
###
### Eric Christensen
<[sparks@fedoraproject.org](mailto:sparks@fedoraproject.org)>
### Jared Smith
<[jsmith@fedoraproject.org](mailto:jsmith@fedoraproject.org)>
### Joshua Wulf
<[jwulf@redhat.com](mailto:jwulf@redhat.com)>
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 . 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](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 {#pref-documentation-guide-Preface}
## 1\. Document Conventions {#idm84024688}
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
### 1\.1. Typographic Conventions {#idm82656208}
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
`Mono-spaced Bold`
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example:
> To see the contents of the file `my_next_bestselling_novel` in your current working directory, enter the **cat my\_next\_bestselling\_novel** command at the shell prompt and press **Enter** to execute the command.
The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example:
> Press **Enter** to execute the command.
>
> Press **Ctrl**+**Alt**+**F2** to switch to a virtual terminal.
The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in `mono-spaced bold`. For example:
> File-related classes include `filesystem` for file systems, `file` for files, and `dir` for directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog-box text; labeled buttons; check-box and radio-button labels; menu titles and submenu titles. For example:
> Choose System → Preferences → Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
>
> To insert a special character into a gedit file, choose Applications → Accessories → Character Map from the main menu bar. Next, choose Search → Find… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose Edit → Paste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
**_`Mono-spaced Bold Italic`_** or _`Proportional Bold Italic`_
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
> To connect to a remote machine using ssh, type **ssh _`username`_@_`domain.name`_** at a shell prompt. If the remote machine is `example.com` and your username on that machine is john, type **ssh john@example.com**.
>
> The **mount -o remount _`file-system`_** command remounts the named file system. For example, to remount the `/home` file system, the command is **mount -o remount /home**.
>
> To see the version of a currently installed package, use the **rpm -q _`package`_** command. It will return a result as follows: **_`package-version-release`_**.
Note the words in bold italics above: username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
> Publican is a _DocBook_ publishing system.
### 1\.2. Pull-quote Conventions {#idm64946960}
Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in `mono-spaced roman` and presented thus:
books Desktop documentation drafts mss photos stuff svn
books_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in `mono-spaced roman` but add syntax highlighting as follows:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object ref = iniCtx.lookup("EchoBean");
EchoHome home = (EchoHome) ref;
Echo echo = home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}
### 1\.3. Notes and Warnings {#idm1555104}
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
### Note
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
### Important
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled “Important” will not cause data loss but may cause irritation and frustration.
### Warning
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
## 2\. We want feedback {#idm60858352}
If you find errors or have suggestions for improvement, we want your advice. Submit a report in Bugzilla against the product `Fedora Documentation` and the component `documentation-guide`. The following link automatically loads this information for you: [https://bugzilla.redhat.com/enter\_bug.cgi?product=Fedora%20Documentation&component=documentation-guide](https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora%20Documentation&component=documentation-guide).
In Bugzilla:
1. Provide a short summary of the error or your suggestion in the `Summary` field.
1. Copy the following template into the `Description` field and give us the details of the error or suggestion as specifically as you can. If possible, include some surrounding text so we know where the error occurs or the suggestion fits.
Document URL:
Section number and name:
Error or suggestion:
Additional information:
1. Click the Submit Bug button.
# Chapter 1. Introduction {#chap-documentation_guide-intro}
## 1\.1. Purpose of This Guide {#idm47741152}
The purpose of this guide is to help you be successful as a writer, and to gain a better understanding of the tools and techniques that the Fedora Documentation team use. We hope you'll dive right in and use this information to your advantage, and that it will also inspire you to join in our efforts to improve Fedora documentation.
This introductory chapter will introduce you to some of the best practices that the Fedora Documentation Project uses to help its writers be most productive. In subsequent chapters, we'll walk you through a tutorial designed to teach you the tools and workflow we use. Later in the book, we'll cover more advanced topics, such as publishing and translation. Near the end of the book, we also include a style guide, which is intended to help bring a higher level of consistency and professionalism to all of the Fedora documentation.
## 1\.2. Tips for Success {#idm50697184}
Before we dive into the mechanics of writing and publishing documentation, let's look at some important points that will help ensure your success in your documentation efforts.
**Be Bold!**
: Although it might seem a bit trite at first glance, the most important part of writing documentation is writing. There's no need to ask permission before writing... just start writing! We also use technology to keep track of all the changes that happen in our guides, so don't let your fear of ruining something keep you from moving forward. If you do somehow manage to mess things up, we can always roll back to a previous version.
**Don't Let the Tools Scare You**
: The Fedora documentation group uses a number of different tools, but please don't be intimidated by the tools. A bit of practice and mentoring may be necessary to get proficient with the tools. In the meantime, just write in a text editor of your choice, and the text can always be converted into the proper format at a later time, either by you or by another member of the Fedora Documenation team. Too many times, we see people stop contributing when they feel uncomfortable with the tools. If the tools scare you, please keep writing and let other members of the team deal with the tools.
We will discuss the various tools in [Chapter 5, _XML Tools_](#chap-documentation_guide-tools "Chapter 5. XML Tools").
**There's a Team to Back You Up**
: Don't be afraid to ask for assistance. The Fedora documentation team is more than willing to help you both with writing and with learning the tools and workflow. If you're familiar with the IRC chat system, please join the `#fedora-docs` channel on the Freenode network. We also have a mailing list where we discuss various issues related to documentation. For more information on the joining the mailing list, visit .
## 1\.3. Organization of this Guide {#idm95022096}
In [Chapter 2, _The Fedora Docs Community_](#chap-community "Chapter 2. The Fedora Docs Community"), we will explain the Fedora documentation community, and how you can join the volunteer effort to make the world a better place, one instruction at a time.
In [Chapter 3, _Documentation Workflow_](#chap-documentation_guide-workflow "Chapter 3. Documentation Workflow"), we explain the basic workflow of writing documentation, formatting it, publishing it, and translating it.
In [Chapter 4, _Brief Introduction to DocBook_](#chap-documentation_guide-docbook "Chapter 4. Brief Introduction to DocBook"), we explain the DocBook markup language that we use when publishing our documentation.
In [Chapter 5, _XML Tools_](#chap-documentation_guide-tools "Chapter 5. XML Tools"), we explain the various tools that are used to make the writing and publishing experience easier and more efficient.
In [Chapter 6, _Publican_](#chap-publican "Chapter 6. Publican"), we go into more detail on the Publican toolchain, and how to use it to render and publish your documents.
In [Chapter 7, _Translations_](#chap-documentation_guide-translations "Chapter 7. Translations"), we explain the process and tools around translations, to extend the reach of Fedora documentation into more languages.
Last but certainly not least, we finish the book with [Appendix A, _Style Guide_](#chap-documentation_guide-style "Appendix A. Style Guide").
# Chapter 2. The Fedora Docs Community {#chap-community}
The Fedora Documentation Project , or Fedora Docs , is a global community of techical writers and Fedora enthusiasts that work together to create documentation for Fedora.
## 2\.1. Getting Started {#community-getting_started}
The variety of tools and topics covered by Fedora Docs can make joining an intimidating process. _Don't get discouraged!_ Experienced conributors might be doing in-depth work, but participation doesn't have to be detailed.
We welcome as much time as you would like to contribute, but you don't need to invest a large amount of time to help. Producing quality documention is more than just writing. The work needs to be proofread, periodically checked to see if updates are required, reviewed for technical accuracy, and marked up. Once the documentation is written, it is translated, converted to other formats, and published.
Ways to contribute
* Requesting Documentation. Requesting documentation on a subject might be the simplest way to contribute. If you are looking for instructions for something and can't find it, speak up!
* Proofreading. Proofreading is a task that can be be done by almost anyone. We strongly encourage feedback from readers, as this helps the authors identify confusing or inaccurate content. Reporting content that you have trouble understanding or instructions that don't work as expected helps writers improve their work.
* Reporting Changes. Volunteers testing new software or prerelease versions of Fedora can report new features or changed behaviors. Just knowing what needs to be updated can help writers keep their work up to date.
* Writing. Writing content can be involved, like maintaining a formal guide, or you can share short tutorials. Writing can be the most difficult part of the process, don't worry about doing everything at once. Other volunteers can help with reviewing and publishing.
* Markup. Fedora Documentation is eventually saved in the DocBook format. Using DocBook provides structure and context, enables effective translation, and allows publishing in a variety of formats. You can learn more about DocBook in [Chapter 4, _Brief Introduction to DocBook_](#chap-documentation_guide-docbook "Chapter 4. Brief Introduction to DocBook").
* Translating. The [Fedora Localization Project](https://fedoraproject.org/wiki/L10N) translates Fedora's documentation and some software. Localization (often abbreviated as L10N, where the `10` represents the number of letters between `L` and `N` in the word in English) is a separate group within Fedora that often works closely with the Docs Project.
* Publishing. A document is ready to be published when the relevant change has been identified and the documentation written or updated. More publishing is done as the content is translated to various languages. Volunteers publish work to make it available to the Fedora community.
* Mentoring. More experienced members of the Docs community act as mentors for others. Don't ever be afraid to ask for help from your mentor, or from anyone on the Docs team. Friendship is one of Fedora's [Foundations](https://fedoraproject.org/wiki/Foundations), and many have found valuable friendships in the Fedora community.
## 2\.2. Mentors {#community-mentoring}
## 2\.3. Communication {#community-communication}
## 2\.4. Office Hours {#community-office_hours}
# Chapter 3. Documentation Workflow {#chap-documentation_guide-workflow}
This chapter will introduce you to the basic workflow of documents as they're written, converted, translated, and published.
## 3\.1. Write First, Format Later {#idm60637456}
## 3\.2. Formatting in DocBook {#idm60638864}
## 3\.3. Pushing Strings to Translation {#idm60639760}
Pushing strings to translation is discussed in [Chapter 7, _Translations_](#chap-documentation_guide-translations "Chapter 7. Translations").
## 3\.4. Pulling Strings from Translation {#idm4302832}
Pulling strings from translation is discussed in [Chapter 7, _Translations_](#chap-documentation_guide-translations "Chapter 7. Translations").
## 3\.5. Building Documents {#idm4304864}
Building documents is discussed in [Section 6.4, “Building a Document”](#sect-publican-building "6.4. Building a Document").
## 3\.6. Publishing Documents to the Web {#idp6140560}
Publishing documents to the web is discussed in [Section 6.5, “Publishing a Document”](#sect-publican-publishing "6.5. Publishing a Document").
## 3\.7. Building Packages from Documents {#idp6138544}
Building packages from documents is discussed in [Section 6.6, “Packaging a Document”](#sect-publican-packaging "6.6. Packaging a Document").
## 3\.8. Creating a patch {#sect-workflow-patching}
Patches are files that show changes between two versions of a file. The patch file can be shared via email or in a bug report, easily reviewed, and applied without requiring additional manual editing. This section details the procedure for creating a patch for a Fedora Guide.
Example 3.1. An example of a patch file
A patch file might look like this one.
From a6419e00b515765085cc4e646c3822ebdda607df Mon Sep 17 00:00:00 2001
From: Pete Travis <immanetize@fedoraproject.org>
Date: Mon, 30 Dec 2013 21:52:57 -0700
Subject: [PATCH] Update commands for starting, stopping, and checking the
status of abrtd to use systemctl instead of service/chkconfig
---
en-US/Automatic_Bug_Reporting_Tool_ABRT.xml | 20 ++++++++++----------
1 file changed, 10 insertions(+), 10 deletions(-)
diff --git a/en-US/Automatic_Bug_Reporting_Tool_ABRT.xml b/en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
index 1093dc8..f01bb33 100644
--- a/en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
+++ b/en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
@@ -88,18 +88,18 @@
Your next step should be to verify that <systemitem
class="daemon">abrtd</systemitem> is running. The daemon is typically configured to start up at boot time. You can use the following command as root to verify its current status:
</para>
- <screen>~]# <command>service abrtd status</command>
+ <screen>~]# <command>systemctl status abrtd</command>
abrtd (pid 1535) is running...</screen>
<para>
- If the <command>service</command> command returns the <computeroutput>abrt is stopped</computeroutput> message, the daemon is not running. It can be started for the current session by entering this command:
+ If the <command>systemctl</command> command returns the <computeroutput>Active: inactive (dead)</computeroutput> message, the daemon is not running. It can be started for the current session by entering this command:
</para>
- <screen>~]# <command>service abrtd start</command>
+ <screen>~]# <command>systemctl start abrtd </command>
Starting abrt daemon: [ OK ]</screen>
<para>
- You can run the following <command>chkconfig</command> command to ensure that the <systemitem
+ You can run the following <command>systemctl</command> command to ensure that the <systemitem
class="daemon">abrtd</systemitem> service initializes every time the system starts up:
</para>
- <screen>~]# <command>chkconfig abrtd on</command></screen>
+ <screen>~]# <command>systemctl enable abrtd </command></screen>
<para>
Similarly, you can follow the same steps to check and configure the <systemitem
class="service">abrt-ccpp</systemitem> service if you want <application>ABRT</application> to catch C/C++ crashes. To set <application>ABRT</application> to detect kernel oopses, use the same steps for the <systemitem
@@ -119,12 +119,12 @@ kernel.panic = 0</screen>
<para>
Finally, you can verify that the <systemitem
class="service">ABRT notification applet</systemitem> is running:
- </para>
- <screen>~]$ <command>ps -el | grep abrt-applet</command>
+ </para>
+ <screen>~]$ <command>ps -el | grep abrt-applet</command>
0 S 500 2036 1824 0 80 0 - 61604 poll_s ? 00:00:00 abrt-applet</screen>
- <para>
- If the <application>ABRT</application> notification applet is not running, you can start it manually in your current desktop session by running the <systemitem
- class="service">abrt-applet</systemitem> program:
+ <para>
+ If the <application>ABRT</application> notification applet is not running, you can start it manually in your current desktop session by running the <systemitem
+ class="service">abrt-applet</systemitem> program:
</para>
<screen>~]$ <command>abrt-applet &</command>
[1] 2261</screen>
--
1.8.4.2
Let us examine how this patch file was created. In the following procedure, we will create a patch to correct a line in the _System Administrators Guide_ to update from the legacy **service** to the current **systemctl** command.
Procedure 3.1. Patch creation workflow
1. First, find the guide you want to work on in the table at [https://fedoraproject.org/wiki/Docs\_Project\_guides\_table](https://fedoraproject.org/wiki/Docs_Project_guides_table).
1. The `repo` column of the table has a link to the guide's git repository. Open the link, and you'll see the `Clone` section at the bottom of the page, listing the repository's URLs.
1. If you have set up ssh keys for your [FAS](https://admin.fedoraproject.org/accounts) account, right click the URL that begins with `ssh://` and select Copy Link Location.
If you have not set up ssh keys in FAS, or simply want to clone anonymously, right click the url that begins with `https://` and select Copy Link Location.
It is a good idea to use the `ssh://` url, even if you do not currently have commit access. If you later gain commit access, you won't have to go back and change the upstream location of the repo.
1. In a terminal window, change to the directory you have chosen to store guides in and clone the repo. You can paste into the terminal window by right clicking it and selecting Paste. Some terminal applications will also paste with the key combination **Shift**+**Insert**.
**cd ~/fedora-docs**
** git clone ssh://git.fedorahosted.org/git/docs/system-administrators-guide.git **
**cd system-administrators-guide**
1. If you have already cloned the repo, it is important to make sure your local copy is updated and matches the remote copy.
Pull in new changes from remote:
**git pull**
If you have made changes in the master branch that aren't committed, you can **stash** them. The files will returned to the unchanged state, and you can come back to them later. For detailed information, refer to **man git-stash**.
**git stash**
# continue with patch process, then bring back your stashed state with:
**git stash pop**
If you have made _and committed_ changes in the master branch, you should push your changes:
**git push**
If you don't have access to push commits, or you don't want to push them, you can reset your local copy to match remote:
**git reset --hard origin/master**
1. A new branch of the repository will allow you to make changes to the side, without affecting the master branch until we are ready to. For smaller patches, this branch is temporary and you won't have to share it. Name the branch something recognizable to help you keep track of its purpose, then check out the branch.
**git branch abrt-systemctl-not-service**
**git checkout abrt-systemctl-not-service**
1. Find the files you need to change. A bug report might say "The abrt section should use the systemctl command instead of service", but it will not tell you what file or section to edit. In DocBook, commands are usually wrapped in the <command> tag, so we can use that to help our search.
**grep "<command>service" en-US/*.xml**
`en-US/Automatic_Bug_Reporting_Tool_ABRT.xml`: <screen>~]# _<command>service_ abrtd status</command>
`en-US/Automatic_Bug_Reporting_Tool_ABRT.xml`: If the _<command>service_</command> command returns the <computeroutput>abrt is stopped</computeroutput> message, the daemon is not running. It can be started for the current session by entering this command:
`en-US/Automatic_Bug_Reporting_Tool_ABRT.xml`: <screen>~]# _<command>service_ abrtd start</command>
1. The **grep** command has found the file we want to edit, `en-US/Automatic_Bug_Reporting_Tool_ABRT.xml`. Open the file in your favorite editor and make the required changes:
**vim `en-US/Automatic_Bug_Reporting_Tool_ABRT.xml`**
or:
**emacs `en-US/Automatic_Bug_Reporting_Tool_ABRT.xml`**
or:
**gedit `en-US/Automatic_Bug_Reporting_Tool_ABRT.xml`**
The editor you choose is not important, but the file must be saved in plain text format.
Change only the content you need to, so that the diff will be more readable. Resist the temptation to rephrase passages unless they are misleading, to avoid making more work for translators. Do not adjust sections to your preferred indentation depth; this changes no actual content and makes the patch more difficult to interpret.
1. Test your changes by building the document, and reviewing the section in the browser.
**publican build --langs en-US --formats html**
**firefox tmp/en-US/html/index.html**
1. After editing, if you want to check what files you have changed, use this command:
**git status**
` # On branch abrt-systemctl-not-service # Changes not staged for commit: # (use "git add ..." to update what will be committed) # (use "git checkout -- ..." to discard changes in working directory) # # modified: en-US/Automatic_Bug_Reporting_Tool_ABRT.xml # no changes added to commit (use "git add" and/or "git commit -a") `
1. Commit your changes. If you only made a few changes, place them all in the same commit. If you make many changes, edit different files, or work on varied issues, spread your changes out into individual commits. This makes it easier for others to follow your work.
**git commit en-US/Automatic_Bug_Reporting_Tool_ABRT.xml**
After you run the command above, an editor will open for you to enter a commit message. Be descriptive, explain what sections you have updated and why, and provide references if available. If you are working on a specifig bug report, you should also cite the bug in the commit message. something like `RHBZ#439858` is enough but you can also cite the full URL if you prefer.
### Default Editor
The default editor used by git is vi. You can change this setting by adding a line in `~/.bashrc`, such as:
**export EDITOR="/usr/bin/emacs"**
You can also bypass the editor and enter your message directly with the commit command, like this:
** git commit en-US/Automatic_Bug_Reporting_Tool_ABRT.xml \ -m "Update commands for starting, stopping, and checking the status \ of abrtd to use systemctl instead of service/chkconfig" **
1. Check the status of your repository again, and make sure all the indended changes have been committed.
**git status**
` # On branch abrt-systemctl-not-service nothing to commit, working directory clean `
1. Now create your patches. Each commit will create one patch file, showing the differences between your changes and the master branch.
**git format-patch master**
` 0001-Update-commands-for-starting-stopping-and-checking-t.patch `
1. Now that you've created the patch, share it! Attach it to the bug ticket, send it to the mailing list, or share it with your mentor. The patch needs to get out for review and inclusion in the master branch.
If there isn't an existing bug, you can create a new one. The patch created when writing this section is attached to [https://bugzilla.redhat.com/show\_bug.cgi?id=1047428](https://bugzilla.redhat.com/show_bug.cgi?id=1047428)
1. After you have shared your patch, you can clean up. Checking out the master branch will return the files to the unedited state:
** git checkout master **
Clean any files that git is not tracking from the directory. This will delete your patches, so make sure you have sent them off for review.
** git clean -xdf **
You can delete the local working branch as well. Again, make sure you have shared your patches, or your work will be lost.
**git branch -D abrt-systemctl-not-service**
`Deleted branch abrt-systemctl-not-service (was a6419e0).`
1. After review, the patch can be downloaded and then applied using git:
**git apply 0001-Update-commands-for-starting-stopping-and-checking-t.patch**
# Chapter 4. Brief Introduction to DocBook {#chap-documentation_guide-docbook}
This chapter will give you a brief introduction to DocBook.
## 4\.1. Why DocBook? {#sec-Why_DocBook}
DocBook has many features that make it suitable for documentation in Fedora and other projects.
### 4\.1.1. DocBook as an XML Markup Language {#sec-DocBook_as_an_XML_Markup_Language}
DocBook is an implementation of _Extensible Markup Language (XML)_. XML gives DocBook powerful flexibility.
### 4\.1.2. Human-readable Tags {#sec-Human-readable_Tags}
DocBook tags are generally self-explaining. They are named after what they define, even though shorter terms might make more efficient use of space. This makes it easy for writers and editors to quickly look at a document and understand how it is constructed.
### 4\.1.3. Text-based Format for Easy Revision Control {#sec-Text-based_Format_for_Easy_Revision_Control}
Version control provides two critical features for collaborative documentation work: concurrent editing and history. The text-based format of DocBook makes it well-suited to being managed by a version control system.
### 4\.1.4. Separation Between Content and Style {#sec-Separation_Between_Content_and_Style}
The DocBook standard separates a document's content and its formatting. The writer uses XML tags to structure the elements of document, and the formatting can be changed independently later. A change to the formatting of an element does not require changing every instance of that element.
### 4\.1.5. Output in a Variety of Formats {#sec-Output_in_a_Variety_of_Formats}
DocBook is a source format. The **publican** tool is used to generate rendered documents in several different formats. publican can generate HTML, PDF, and epub formats from the same source file.
## 4\.2. Parts of a DocBook File {#sec-Parts_of_a_DocBook_File}
### 4\.2.1. Entities {#sec-Entities}
Entities are like variables. They allow for one change to be reflected many times in a document. Entities are usually defined early in the document using the following syntax:
<!ENTITY ENTITYNAME "value">
Entities are then referred to in the document source with `&`_`ENTITYNAME`_`;`. The most common use of entities are for phrases like the current version of a product or the product name.
### Warning
Entities do not appear in the PO files for a document, and are therefore untranslateable. Only use an entity for wording that does not require translation ("Fedora", for example)
## 4\.3. Dividing a Document into Multiple Files with XIncludes {#sec-Dividing_a_Document_into_Multiple_Files_with_XIncludes}
As a document grows, managing it as a single file becomes challenging. In addition, having multiple files compose a single document allows for some files to be reused between documents, reducing the overhead for a large documenatation package. Fortunately, DocBook supports including multiple file. To include an additional file into a document, refer to the following example:
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="_`Included_File.xml`_" />
When the document is rendered, the included text will appear as if it were inserted entirely in the main file.
# Chapter 5. XML Tools {#chap-documentation_guide-tools}
This chapter will walk you through a few of the commonly-used XML tools that will make it easier to work with DocBook files.
## 5\.1. XML Concepts {#idm62189776}
_Extensible Markup Language_ or XML is the language that is used in Docbook. We use docbook to write all of the documentation, so it is a good idea to be familiar with XML terminiolgy and with resources to use in order to edit and check your XML.
XML is a markup language similar to HTML and SGML, the unique difference is that the tags `` can be specialized, as long as they are valid for the DTD (which in Fedora Docs is held by Docbook). Your best friend for tags, and how to use them will be found at the [DocBook tag Reference](http://www.docbook.org/tdg/en/html/part2.html).
Here is some information that will help you be able to talk about XML correctly so that if you need to ask a question you won't embarrass yourself.
* XML has a tree like hirarchy where tags are nested. The outer most tag is the parent, and all the tags inside it are its respective children. If your text editor allows for nested tags, each child will be able to collapse inside the parent.
* Once you look at a tag it may have several components:
* `` this is the tag name. It can be a parent or a child.
* `attribute` - an attribute gives a special characteristic to an element. To see which elements take which attributes refer to the [DocBook tag Reference](http://www.docbook.org/tdg/en/html/part2.html)
* `="value"` - attributes have values assigned to them. They can be numerical or they can be text strings. For valid attribute values, refer to the [DocBook tag Reference](http://www.docbook.org/tdg/en/html/part2.html).
## 5\.2. xmllint {#idm95780576}
xmllint is a useful tool to use to check your XML files. Sometimes **publican build** will give you an error that may be difficult to interpret. xmllint's parser can give more accurate details as to the location of the error and also can give you a description that makes more sense to a human. Another advantage to xmllint is that it can process a single XML file whereas **publican build** must parse the entire book. The xmllint package can be installed using the **yum install xmllint** as follows:
# **yum install xmllint**.
**xmllint _`name-of-file`_**
## 5\.3. xsltproc {#idm76787440}
some more stuff here
## 5\.4. xmltidy {#idm49608240}
and even more here
# Chapter 6. Publican {#chap-publican}
Publican is an open-source publishing system for documentation authored in DocBook XML. It can be used to create and build individual articles and books, manage multiple book sets, or to maintain entire documentation websites. In addition, it can also be used to create RPM packages for easy distribution of documentation builds to other machines.
Publican produces high-quality documents in a number of commonly used file formats such as HTML, PDF, or EPUB. To ensure that all documents produced for a specific project have a consistent look, it uses so-called _brands_ to add logos, define color schemes, and set the overall visual style of the output files.
The Fedora Documentation Project uses Publican to produce all documents located on the [Fedora Documentation](http://docs.fedoraproject.org/) website.
## 6\.1. Installing Publican {#sect-publican-installing}
To install Publican itself and the `fedora` brand that is used by the Fedora Documentation Project, type the following at a shell prompt as `root`:
**yum install publican publican-fedora**
By default, only the `common` brand is installed with the publican package. There are many brands in Fedora repositories, such as `oVirt` (publican-ovirt), `JBoss` (publican-jboss), or `genome` (publican-genome).
## 6\.2. Creating a New Document {#sect-publican-creating}
When creating a new document, Publican allows you to choose between a book and an article. Compared to books, articles have a simpler structure, do not have a preface or a separate title page, and generally tend to be much shorter. Use an article if you intend to write a text with only a few pages. For larger documents, it is usually better to use a book.
To create a new book, type the following at a shell prompt:
**publican create --type book --name "_`Document Name`_" --brand _`brand`_**
Replace _`Document Name`_ with the document title and _`brand`_ with the brand you want to use (typically `fedora`). Similarly, to create a new article, run the following command:
**publican create --type article --name "_`Document Name`_" --brand _`brand`_**
Additionally, you can specify the `--lang` option followed by a language code (such as `pt-BR` or `cs-CZ`) to write the book in a language different than English.
The **publican create** command creates a new directory named _`Document_Name`_. This directory contains the `publican.cfg` configuration file and another directory named after the language code (that is, `en-US/` by default), which contains boilerplate files as described in [Table 6.1, “Files Created By Publican”](#tabl-publican-creating "Table 6.1. Files Created By Publican").
Table 6.1. Files Created By Publican
|Book|Article|Description|
|-|
|``_`Document_Name`_.ent``|``_`Document_Name`_.ent``|Contains local entities, such as `YEAR` and `HOLDER`, that are used in the copyright notice.|
|``_`Document_Name`_.xml``|``_`Document_Name`_.xml``|The main XML file that includes other files. Articles are usually written in this file.|
|`Book_Info.xml`|`Article_Info.xml`|Contains the document metadata, such as the title, subtitle, product name, or abstract.|
|`Author_Group.xml`|`Author_Group.xml`|Contains information about the document authors, editors, and other contributors.|
|`Revision_History.xml`|`Revision_History.xml`|Contains the revision history. Publican uses this file when it creates an RPM package.|
|`Preface.xml`|—|Contains the default preface. Articles do not use this file.|
|`Chapter.xml`|—|Contains a template of the first chapter. Articles do not use this file and a similar template is included in the main XML file instead.|
## 6\.3. Validating a Document {#sect-publican-validating}
To check your document and ensure that all source files are valid DocBook XML, type the following at a shell prompt:
**publican build --langs _`languages`_ --formats test**
Replace _`languages`_ with a comma-separated list of language codes (such as `en-US` or `cs-CZ`). Note that when you build a document as described in [Section 6.4, “Building a Document”](#sect-publican-building "6.4. Building a Document"), Publican automatically validates it for you.
## 6\.4. Building a Document {#sect-publican-building}
To build a document in order to review it, use the following command:
**publican build --langs _`languages`_ --formats _`formats`_**
Replace _`languages`_ with a comma-separated list of language codes (such as `en-US` or `cs-CZ`) and _`formats`_ with a comma-separated list of file formats as described in [Table 6.2, “Available Target Formats”](#tabl-publican-building "Table 6.2. Available Target Formats").
By default, the **publican build** command stores the created files in the `tmp/` directory where you can review the output. To build a final version of the document, add the `--publish` option as follows:
**publican build --publish --langs _`languages`_ --formats _`formats`_**
This places the generated files in the `publish/` directory. For information on how to publish your document on the Fedora Documentation website, see [Section 6.5, “Publishing a Document”](#sect-publican-publishing "6.5. Publishing a Document").
Table 6.2. Available Target Formats
|Format|Description|
|-|
|`html`|Generates multiple HTML pages.|
|`html-single`|Generates a single HTML page.|
|`html-desktop`|Generates a single HTML page with a table of contents in a sidebar.|
|`pdf`|Generates a PDF file.|
|`epub`|Generates an EPUB file.|
|`txt`|Generates a plain-text file.|
|`man`|Generates a manual page.|
|`eclipse`|Generates an Eclipse help plug-in.|
|`test`|Does not generate any files, only validates the XML files.|
## 6\.5. Publishing a Document {#sect-publican-publishing}
### 6\.5.1. Adding a New Document {#sect-publican-publishing-adding}
In order to publish an entirely new document or a new major version of an already published document on the [Fedora Documentation](http://docs.fedoraproject.org/) website, [open a support ticket with Fedora Release Engineering](https://fedorahosted.org/rel-eng/newticket) and request addition of the relevant RPM package name (for example `Fedora-Security_Guide-19-web-en-US`) to the `el6-docs` repository. Package names of documents created by Publican have the following format:
_`product_name`_-_`document_title`_-_`product_number`_-web-_`language`_
To help you determine the correct package name for your document, you can run the following command in the main directory of your document:
**publican package --lang _`language`_**
Replace _`language`_ with a selected language code (such as `en-US` or `cs-CZ`). This command packages your document as a source RPM (SRPM) and prints the absolute path to this package to standard output.
### 6\.5.2. Updating a Document {#sect-publican-publishing-updating}
To publish your document on the [Fedora Documentation](http://docs.fedoraproject.org/) website, complete the following steps:
1. Make sure that the `publican.cfg` file in the main directory of your document contains the following line:
os_ver: .el6
1. Update the ``_`language`_/Revision_History.xml`` file to ensure that the document has a unique revision number. To create a new entry in the revision history, use the following command:
**publican add_revision --lang _`language`_ \**
**--firstname _`first_name`_ --surname _`surname`_ --email _`email`_ \**
**--member "_`description`_"**
Replace _`language`_ with a selected language code (such as `en-US` or `cs-CZ`), _`first_name`_ with your given name, _`surname`_ with your surname, _`email`_ with your email address, and _`description`_ with a brief description of your changes.
1. Package your document as a source RPM (SRPM):
**publican package --lang _`language`_**
Replace _`language`_ with a selected language code (such as `en-US` or `cs-CZ`). This command stores the newly created SRPM package in the `tmp/rpm/` directory and prints the absolute path to this file to standard output. If you intend to publish your document in more than one language, repeat this step with a different language code.
1. Push the SRPM package created in the previous step to Koji:
**koji build el6-docs _`package_name`_**
Replace _`package_name`_ with a path to the SRPM package (for example, `tmp/rpm/Fedora-Security_Guide-19-web-en-US-19.1-1.el6.src.rpm`).
### 6\.5.3. Removing a Document {#sect-publican-publishing-removing}
## 6\.6. Packaging a Document {#sect-publican-packaging}
# Chapter 7. Translations {#chap-documentation_guide-translations}
Translations are an important piece of the documentation process. If users cannot read the native language that the documentation is written in, then the documentation is not helpful to those users and the hard work that went into the documentation is not being utilized to its fullest extent.
This chapter discusses how translations are provided in Fedora documentation.
## 7\.1. Translating Documentation {#sect-documentation_guide-translations-translating-documentation}
The cornerstone of translation when using XML files such as DocBook is the _Portable Object_ or PO file. PO files provide a way for independent individuals or teams to translate documents.
PO files are usually found in two forms:
* the `.pot` file, or _PO Template_ (POT)
* the `.po` file, or translation file (PO)
A POT is, as the name suggests, a blank template for new translations. It contains some header information and a list of strings based on the content of the original XML file from which it was created. Translators do not alter the POT. The POT should only be changed after changes are made to the original XML file from which it is derived.
PO strings fall into three categories:
1. _translated_, meaning the string has been handled by a translator and its source has not changed since then
1. _fuzzy_, meaning the string has changed since it was last handled by a translator
1. _untranslated_, meaning no translation has yet been provided for this string, or it is brand new
## 7\.2. Introducing Transifex.net {#sect-documentation_guide-translations-introducing-transifex}
The Fedora Project uses Transifex, an open source translation platform, to power the translation of software and documentation. All translations are hosted at [Transifex.net](https://www.transifex.net/), which provides a web application allowing translators to write, submit, and manage their translations. Document translations are then pulled into the document's Git repository, where they can be built and published to [Fedora Documentation website](https://docs.fedoraproject.org).
Documentation maintainers are responsible for the following:
* pushing changes to their guide or other document to Transifex.net
* pulling updated translations back to their git repository
* publishing the translations to [http://docs.fedoraproject.org](https://docs.fedoraproject.org)
The following sections explain how to set up Transifex for use with your document.
## 7\.3. Creating an Account on Transifex.net {#sect-documentation_guide-translations-creating-account}
Go to [Transifex.net](https://www.transifex.net/) and click on Register in the top right hand corner to create an account.
## 7\.4. Installing the Transifex Client {#sect-documentation_guide-translations-installing-client}
To use Transifex with your Git repository, you need the transifex-client package installed from the Fedora repositories.
## 7\.5. Configuring .transifexrc {#sect-documentation_guide-translations-configuring-transifexrc}
Edit the file `~/.transifexrc`, adding your Transifex.net username and password in the following format:
[https://www.transifex.net]
hostname = https://www.transifex.net
username = _`username`_
password = _`password`_
token =
## 7\.6. Initializing Transifex in Your Git Repository {#sect-documentation_guide-translations-initializing-transifex}
Go to the Git repository of your document and change to the current Fedora release branch. Alternatively, you can create a new branch specifically for translations by branching the release branch, and then periodically merge updated content from the release branch to the branch with translations. After choosing the approach that is appropriate for you and changing to the branch, enter the following commands, replacing ``_`url`_`` with the URL of your document's project page on Transifex.net:
tx init
tx set --auto-remote _`url`_
This will create a `.tx` folder in your repository.
### I cannot find my document on Transifex.net!
Most Fedora documents already have a project page on Transifex.net, but if your document is new you may need to set one up. Ask on the Fedora Docs Project mailing list for help with how to do this.
## 7\.7. Mapping Language Codes {#sect-documentation_guide-translations-mapping-language-codes}
If you have translation folders already in your repository, you may need to map the language codes to the ones used by Transifex.net, if they are different.
To do this, open the file `.tx/config`. You should see a `[main]` section which allows you to set configurations for the whole document, followed by sections for the individual files of which your document is comprised (_resources_, in Transifex terminology). In the `[main]` section, edit the `lang_map` line to map the language codes in your repository to the ones used on Transifex.net. For example, if your repository uses `ro-RO` for Romanian and `bg-BG` for Bulgarian, but Transifex.net uses `ro` and `bg` respectively, the `lang_map` line should look like this:
lang_map = ro:ro-RO,bg:bg-BG
The language code used in Transifex.net comes first, followed by the language code used by the folder in your repository. Multiple language mappings are given as a comma-separated list.
### Finding currently active Translation Teams
To find out what Translation Teams currently have translations for your document, and to see what language code they use, click on All Resources under Project Releases on your document's Transifex.net project page. This will bring up a list of all currently active Translation Teams, with the name of each language followed by its language code in parentheses. You can also see how much of your document each team has translated, and the details of the last submitted translation.
For your `.tx/config` file you can simply reuse the following language code mappings, which are utilized by a number of Fedora guides that are tracked by Transifex.net:
lang_map = aln:aln-AL, ar:ar-SA, as:as-IN, ast:ast-ES, bal:bal-PK,
bg:bg-BG, bn:bn-BD, bn_IN:bn-IN, bs:bs-BA, ca:ca-ES, cs:cs-CZ, da:da-DK,
de_CH:de-CH, de:de-DE, el:el-GR, en_GB:en-GB, es:es-ES, et:et-EE, eu:eu-ES,
fa:fa-IR, fi:fi-FI, fr:fr-FR, gl:gl-ES, gu:gu-IN, he:he-IL, hi:hi-IN, hr:hr-HR,
hu:hu-HU, id:id-ID, is:is-IS, it:it-IT, ja:ja-JP, kn:kn-IN, ko:ko-KR, lt:lt-LT,
lv:lv-LV, mai:mai-IN, ml:ml-IN, mr:mr-IN, ms:ms-MY, nb:nb-NO, nds:nds-DE,
nl:nl-NL, nn:nn-NO, or:or-IN, pa:pa-IN, pl:pl-PL, pt_BR:pt-BR, pt:pt-PT,
ro:ro-RO, ru:ru-RU, si:si-LK, sk:sk-SK, sl:sl-SI, sq:sq-AL, sr:sr-RS,
sr@latin:sr-Latn-RS, sv:sv-SE, ta:ta-IN, te:te-IN, tr:tr-TR, tg:tg-TJ, uk:uk-UA,
ur:ur-PK, vi:vi-VN, zh_CN:zh-CN, zh_HK:zh-HK, zh_TW:zh-TW
## 7\.8. Editing File Filters {#sect-documentation_guide-translations-editing-file-filters}
By default, transifex-client downloads translations and stores them in a `translations` folder in your repository. For Fedora documentation, transifex-client must be configured to download the translations to the root folder of your repository, with each language having its own folder, so that Publican can find them.
For each resource listed in the `.tx/config` file, edit the `file_filter` line to give the correct location:
file_filter = <lang>/_`resource`_.po
Replace _`resource`_ with the name of the resource, which is the second part of the section title shown directly above. For example:
[fedora-release-notes.Amateur_Radio]
file_filter = <lang>/Amateur_Radio.po
source_file = pot/Amateur_Radio.pot
source_lang = en
Congratulations, your document repository is now configured for Transifex!
## 7\.9. Updating POT Files {#sect-documentation_guide-translations-updating-pot-files}
Run the following command to update all POT files in your document's repository:
publican update_pot
After running the command, you can proceed with pushing transitions to Transifex.net. Refer to [Section 7.10, “Pushing and Pulling Translations”](#sect-documentation_guide-translations-pushing-pulling "7.10. Pushing and Pulling Translations") for more information.
## 7\.10. Pushing and Pulling Translations {#sect-documentation_guide-translations-pushing-pulling}
Whenever a change is made to your document, run the **publican update\_pot** command. After that, run the following command to push the changes to Transifex.net so that translators can translate them:
tx push -s
If you need to edit a `.po` file locally, you can push the changes back to Transifex.net:
tx push -t
To pull updated translations from Transifex.net:
tx pull -a
You can use the `-l` option to specify specific languages to pull, for example if you know that a particular language has new translations available.
Refer to the Fedora Wiki page [Publishing a document with Publican](https://fedoraproject.org/wiki/Publishing_a_document_with_Publican) for information on how to publish translated documentation to [docs.fedoraproject.org](https://docs.fedoraproject.org).
### Translation notifications
Make sure you select the Watch button on your document's Transifex.net project page to receive email notifications when new translations are available. The Watch button is located below the document's title.
## 7\.11. Branching and Updating Translations Before a New Release {#sect-documentation_guide-translations-branching-updating}
First, change to the branch intended for the previous Fedora release. Then create a new branch for the upcoming release and change to the branch:
git checkout -b _`newbranch`_
Assuming that the content development for the upcoming release happened in the master branch, which is different from the release branch, you should merge the updates from the master branch:
git merge master
After successful merging, check that the resource configuration in the `.tx/config` file is still up-to-date and applies to the current documentation. Especially pay attention to changed, moved or removed chapters in your document. If you need to remove an unused resource, run the following command:
tx delete -r _`documentation`_._`resource`_
For example, if you want to remove the resource Amateur\_Radio from the Fedora Release Notes, execute the following command:
tx delete -r fedora-release-notes.Amateur_Radio
### Use the development version
As of September 2011, you need to have the development version of `transifex-client` installed to use the `tx delete` command. Refer to for instructions on how to get the development version.
When you are done with all necessary changes, follow the usual procedure with updating POT files and pushing and pulling translations that is described in [Section 7.9, “Updating POT Files”](#sect-documentation_guide-translations-updating-pot-files "7.9. Updating POT Files") and [Section 7.10, “Pushing and Pulling Translations”](#sect-documentation_guide-translations-pushing-pulling "7.10. Pushing and Pulling Translations").
## 7\.12. Additional Resources {#sect-documentation_guide-translations-additional-resources}
Setting up and using Transifex.net is also explained on Fedora Wiki, at [https://fedoraproject.org/wiki/Setting\_up\_a\_document\_with\_Transifex](https://fedoraproject.org/wiki/Setting_up_a_document_with_Transifex).
### Getting more help
Transifex.net has its own comprehensive documentation for transifex-client at . You can also post questions to the Docs Project mailing list or ask in the `#fedora-docs` IRC channel if you get stuck. The L10N Guide has lots of useful information on using Transifex from a translator's perspective: .
# Appendix A. Style Guide {#chap-documentation_guide-style}
Writing high-quality documents that are easily understood by multiple readers can be a difficult challenge. There are many different techniques that can be used in writing, and there are many different ways of writing the same information. In order to provide consistent, readable documentation, certain standards must be established. There are many different writing-style guides that serve different purposes and audiences. Good style is something learned and practiced.
The Fedora Documentation Project is tasked with producing friendly, easy-to-read documentation for a worldwide audience. This means writing clean, clear documents with great attention to differences in cultures and languages. The Fedora Documentation Style Guide outlines specific rules and recommendations for documentation contributors. The style guidelines standardize documentation of both technical and non-technical information to increase readability and comprehension.
The writers producing Fedora documentation come from a variety of backgrounds, each with different skill sets. Through the use of the _Fedora Documentation Style Guide_, contributors produce and collaborate on documentation with consistent results. This style guide may vary from each contributor's familiar writing requirements. Practicing this guide will eventually become a comfortable standard with benefits outside of Fedora documentation. This style guide will demonstrate the rules and guidelines it sets forth.
The _Fedora Documentation Style Guide_ borrows many ideas from the Associated Press (AP) Stylebook and The Chicago Manual of Style. Any differences from those guides are intended to enhance the value of documents for international readers, and accommodate the technical nature of Fedora documentation. Particular care is made to adopt international standards for common notations to avoid confusion across cultural lines.
## A.1. General Guidelines {#sect-documentation_guide-style-general_guidelines}
The following sections provide guidelines for both sentence composition and syntax usage. Follow these guidelines to ensure your document's tone is consistent with that of other Fedora documentation.
### A.1.1. Composition {#sect-documentation_guide-style-general_guidelines-composition}
#### A.1.1.1. Voice {#sect-documentation_guide-style-general_guidelines-composition-voice}
Instructions and rules use an _active voice_, presenting confidence to the reader without sounding demanding. An active voice provides clear direction. It shows the reader what to do and gives expected results. Active voice leaves the reader with the impression an author stands behind the written work.
### Warning
Passive voice is completely correct grammatically, but it is a barrier to reader comprehension. The passive voice flips conventional sentence structure around. It moves the verb and direct object forward to the first half of a sentence and places the main subject in the second half of a sentence. Often a simple restructuring of the sentence makes it active. Long passive sentences frequently take multiple reads before a reader grasps the full meaning.
|ACTIVE: Select a strong password to improve personal security.|
|PASSIVE: Personal security improves by a strong password being selected.|
#### A.1.1.2. Context {#sect-documentation_guide-style-general_guidelines-composition-context}
Avoid writing out of context. Adhere carefully to the subject matter of the document, chapter, section, and paragraph. Use references as appropriate, structuring documents so each new part builds upon the last. Avoid making the reader skip ahead to put current parts in context. Provide a link to related documentation if the reader may need it for clarification.
#### A.1.1.3. Emphasis {#sect-documentation_guide-style-general_guidelines-composition-emphasis}
Emphasis is most effective when used sparingly. Use methods of emphasis, such as boldface, underlining, or oblique text, to draw attention to a new term. Use admonitions to set off notable material. Another acceptable way to emphasize a point is with varying sentence formation or word choice. The best documentation writers plan ahead for emphasis, applying it with careful consistency throughout the document.
#### A.1.1.4. Accuracy and Precision {#sect-documentation_guide-style-general_guidelines-composition-accuracy_and_precision}
Accuracy and precision make or break any document. This axiom applies equally to technical and literary accuracy. Choose words after considering as many usage cases as possible. For example, "go to" is not as precise as "click," yet "click" may not be accurate for all interface interactions. The term "select" is accurate in any usage case and sufficiently precise. Don't become too preoccupied in an attempt to cover all potential usage cases. Covering rare side cases elongates a document beyond reason, and the reader loses focus.
#### A.1.1.5. Tense {#sect-documentation_guide-style-general_guidelines-composition-tense}
Tense is the time in which language takes place. There are three main tenses: past, present, and future. Select an appropriate tense for the document and adhere to it. For technical documentation, use the present tense whenever possible. Maintaining the same tense for each statement in a document is vital for clarity. Keep the same tense for all sequential tasks in a procedure.
### A.1.2. Usage {#sect-documentation_guide-style-general_guidelines-Usage}
#### A.1.2.1. Contractions {#sect-documentation_guide-style-general_guidelines-Usage-Contractions}
Avoid contractions, the combination of two words with an apostrophe replacing one or more letters. Contractions reduce the readability of documents and make translation more difficult. Other cultures and languages interpret contractions differently, and this confusion conflicts with the goals of the Fedora Documentation Project.
#### A.1.2.2. Pronouns {#sect-documentation_guide-style-general_guidelines-Usage-Pronouns}
Pronouns are words languages use to replace specific noun phrases. Good writers must strike a balance between over-repeating a noun phrase and using pronouns to stand in for nouns. A general rule to preserve clarity is to never repeat noun substitution with a pronoun in two consecutive sentences. Readers of technical documents need constant reminders on the exact subject the author is writing about. Prevalent use of pronouns causes readers to guess the subject a sentence is referencing. These assumptions reduce the effectiveness of documentation.
Avoid most personal pronouns in documentation, including the following:
|Subjective personal pronouns ("I," "he," "she," "it," "we,")|
|Objective personal pronouns ("me," "her," "him," "us")|
|Possessive personal pronouns ("my," "her," "his," "our")|
Also avoid:
|Reflexive pronouns, such as "yourself" or "himself"|
|Intensive pronouns, such as "he himself" or "(you) do it yourself"|
|Resist overuse of "you", "your", and "one/one's"|
Occasionally, situations require the second personal pronoun "you" and its attendant forms for clarity. Maintaining an active voice is paramount over avoiding the second personal pronouns. "You" and "your" are appropriate words to indicate action or possession on the part of the reader.
Indefinite pronouns, such as "this" or "that", without an antecedent make it tough for a reader to follow an author's meaning. Favor writing an exact noun phrase whenever possible over the vague words "this", "these", "those", and "that."
|INCORRECT: Edit your yum configuration files to use geographically close mirrors. This allows you to update your system faster.|
|CORRECT: Edit the yum configuration files to use geographically close mirrors for faster system updates.|
When eliminating indefinite pronouns, a cumbersome long sentence may result from joining too many clauses. Use indefinite pronouns to break long sentences up to improve clarity, but always provide a proper antecedent.
|INCORRECT: Stay current with recommended updates to your operating system in order to improve functionality of applications, remove security risks, and automatically resolve performance issues solved from bug reports.|
|CORRECT: Stay current with recommended updates to your operating system. These updates improve functionality of applications, remove security risks, and automatically resolve performance issues solved from bug reports.|
#### A.1.2.3. Sentence Formation {#sect-documentation_guide-style-general_guidelines-Usage-sentence_formation}
Keep sentences as short as possible. Cutting unnecessary words is vital to strengthen meaning. There are a number of common traps technical writers fall into resulting in lengthy sentences.
##### A.1.2.3.1. Indirect Discourse {#idm87068480}
Indirect discourse refers to the use of "that" to attribute a statement, fact, or feeling in a sentence without the use of quotation marks. In regular writing, it weakens statements of fact. Documentation writers can improve the impact of sentences by removing "that" and "which".
|INCORRECT: Fedora is an open source operating system that is upstream for many other open source projects.|
|CORRECT: Fedora is an upstream open source operating system for many other open source projects.|
##### A.1.2.3.2. Other Unnecessary Word Combinations {#idm31345808}
Avoid using the unnecessary word "then" following an "if" statement. When a sentence begins with an "if" statement, follow it with a comma and complete the sentence with a full statement.
|INCORRECT: If an email client will not send or receive messages, then check under the File Menu and verify "Work Offline" mode is unselected.|
|CORRECT: If an email client will not send or receive messages, check under the File Menu and verify "Work Offline" mode is unselected.|
Many words we use in everyday conversation reduce impact in printed materials because they "leave a way out". These are words preceding verbs and nouns to minimize the sentence's influence. This is not an exhaustive list, but mindful documentation writers will reduce using these words and those of a similar nature.
### Warning
The following words minimize the impact of the verb or noun clause within a sentence. Other words also fit into this category, but this short list is aimed at helping documentation writers identify words of this nature and eliminate them from their writing: should, could, may, might, perhaps, some, many, most, numerous, few, somewhat, whatever, possibly, can, occasionally, and frequently.
##### A.1.2.3.3. Sentence Variation {#idm77211184}
For the strongest impact, keep the first and last sentences of a paragraph as short as possible. Varying sentence length within a paragraph and through the entire document keeps a reader's attention. A short and simple fact is easy to grasp and use to analyze the next sentence's topic. There is nothing wrong with using longer sentences to explain complex ideas and concepts. Try to use a simple synopsis sentence at the end of each paragraph to give readers a reprieve and recap any important information. A short final sentence stays with the reader to the next section.
#### A.1.2.4. Capitalization {#sect-documentation_guide-style-general_guidelines-Usage-capitalization}
In sentences, capitalize the first word. Do not start sentences with a command, package, or option name.
|INCORRECT: `smolt` provides hardware profiling.|
|CORRECT: The `smolt` package provides hardware profiling.|
In headings, always capitalize the first word regardless of the type of speech. All subsequent words are also capitalized other than articles ("a", "an", or "the"), short prepositions ("in", "of", "for", "with", "at", "on"), or conjunctions ("and", "but", "or").
Examples:
|Avoid Using Contractions in Technical Writing|
|Try to Do the Right Thing|
|Find the Right Way to Say What You Mean|
|The Grass is Always Greener on the Other Side of the Fence|
#### A.1.2.5. Punctuation {#sect-documentation_guide-style-general_guidelines-Usage-punctuation}
Punctuation is a crucial component of understanding prose. A misplaced comma, period, or an improper punctuation mark changes a sentence's meaning entirely. Punctuation marks are the fasteners in a writer's toolbox. Readers are accustomed to the regular nails and screws, like commas and periods. Start throwing in lots of flashy hinges or braces like semicolons or ellipsis, and the unfamiliar notations easily distract readers. Complex punctuation marks are not universal, hindering translation efforts of Fedora Documentation.
Minimize the following punctuation marks in documentation:
|_Parentheses or em dashes_ - To compensate, rearrange the sentence, or break it into two complete thoughts.|
|_Semicolons_ - Good to use only if two thoughts are related, must be joined for clarity, and remove the need for a conjunction.|
|_Colon_ - If there are more than three items, use a bullet list for easy comprehension.|
|_Ellipsis_ - Do not use for stylistic emphasis... only to denote an indefinite continuation of content in an example.|
|_Exclamation points_ - In technical writing this is accepted for use only as a most dire "warning" admonition, not for emphasis.|
|_Ampersands_ - The word "and" is to be written out, and this mark only reserved if it is part of a computer command.|
|_Slashes_ - Do not use slashes for a short hand version of "he or she" by using he/she, instead use the words "and," "or," or "either." Slashes are commonly used in file paths and using them otherwise will create confusion.|
### A.1.3. Other Writing Questions {#sect-documentation_guide-style-general_guidelines-other_writing_questions}
Every writer hits writing obstacles. It becomes difficult to adequately phrase something, or the words just do not "sound right." This is why the Fedora Documentation Project is a team effort. Call on fellow documentation writers in the mailing list or chat room for help with wording and formatting issues. Another trick professional writers use everyday is time away from the project. Take a break away from the document. Returning to a troublesome spot with fresh eyes is often all that is needed to overcome the writing hindrance.
The overall goal of the Fedora Documentation Project is to provide assistance to Fedora users in easy-to-understand language. You do not have to write to impress an English professor, or show off your expertise in a subject matter. Short sentences, frequent definitions of new and unfamiliar terms, and reference links are all aids our audience appreciates most. Write with your target audience in mind, and it will be your documentation contributions with the highest visits of users in need of answers.The following sections provide guidelines for both sentence composition and syntax usage. Follow these guidelines to ensure your document's tone is consistent with that of other Fedora documentation.
## A.2. Content and Rendering {#sect-documentation_guide-style-content_and_rendering}
Writing documentation for display on assorted media through various technologies presents unique requirements. In general, keep the written content and rendering information separate. Rendering information is the formatting markup language to distinguish types of information, such as bold text to add emphasis. Modern technologies empower writers to use specialized markup language to enhance communication. It is imperative writers participating in collaborative projects like the Fedora Documentation Project adhere to standards and prescribed templates.
### Benefits of Content and Markup Language Separation
Keeping content material and markup language separate from each other within documentation adds an additional benefit. As new media formats develop, project coordinators easily remove markup language and re-format the original content for the new communication outlet. Therefore, separating markup language from subject matter content encourages use of the original content for future projects with little additional effort.
## A.3. Dates and Times {#sect-documentation_guide-style-dates_and_times}
The styles used for dates and times vary widely around the world, and this creates a lot of confusion. While there is consensus on one calendar for most business purposes, the dates on this calendar can be represented in many different ways. The varying uses of daylight saving time and assorted ways of representing time can make even simple communications more difficult. International standards have been developed to effectively communicate dates and times, and these standards should be used for publications that may reach a global audience.
### A.3.1. Absolute Dates and Times {#sect-documentation_guide-style-dates_and_times-absolute_dates_and_times}
Absolute dates and times specify specific points in time and may include points in the past, present, or future.
The ISO 8601 standard provides a simple way to represent dates and times that is easily recognized around the world and is equally easy to use. Under this standard, all values are ordered from most to least significant. Write all absolute dates and times in accordance with the ISO 8601 standard.
#### A.3.1.1. Absolute Dates {#sect-documentation_guide-style-dates_and_times-absolute_dates_and_times-absolute_dates}
Absolute dates are written with the four-digit year first, the two-digit month second, and the two-digit day last. Each value is separated with a hyphen. This format is written as "`YYYY-MM-DD`".
#### A.3.1.2. Absolute Times {#sect-documentation_guide-style-dates_and_times-absolute_dates_and_times-absolute_times}
Absolute times are written with the two-digit hour first and the two-digit minute second. Each value is separated by a colon. This format is written as "`HH:MM`".
Additional precision is provided using seconds. Seconds are written as two-digit integers. Minutes and seconds are separated by a colon. This format is written as "`HH:MM:SS`".
Any fraction of a second is written as a decimal number. No limit is placed on the precision used. For example, to use precision of 1/100th of one second, this format is written as "`HH:MM:SS.NN`".
Absolute times are followed by a timezone specification. The Coordinated Universal Time (UTC) is a universally recognized time standard and is preferred for absolute time specifications. This is sometimes referred to as Greenwich Mean Time (GMT) or Zulu Time (Z). The preferred way to specify a time in UTC is to follow the time with a space and "UTC". This format is written as "`HH:MM UTC`".
## A.4. Fedora Specific Conventions {#sect-documentation_guide-style-fedora_specific}
The Fedora Project uses specific conventions that extend beyond the general style rules and guidelines. These conventions exist to produce specific results from the toolchains or to better address the specific requirements of the Fedora Project.
### A.4.1. Screenshots and Images {#sect-documentation_guide-style-fedora_specific-screenshots_and_images}
Images and especially screenshots are hard to maintain, hard to translate, and have to be changed constantly with every test.
Screenshots do not give any more information than is already given with the text. The user is most often following along with the instructions, so the screen is up in front of them already.
Many people perceive that screenshots are necessary in help documents, often because they've seen other documents use screenshots. Avoid this trap. Screenshots lower the quality of the document by taking up valuable space with repetitive imagery and distracting authors from maintaining the far more valuable content.
Diagrams are different from screenshots. A diagram is a graphic that is self-descriptive and in many cases can be very useful or show things that cannot be described as well with words. In such cases it is worth the extra effort to maintain the graphic, including dealing with localization. Fortunately, most documents do not need more than one or two diagrams.
### A.4.2. General Conventions {#sect-documentation_guide-style-fedora_specific-general_conventions}
#### A.4.2.1. Software Management {#sect-documentation_guide-style-fedora_specific-general_conventions-software_management}
Software that appears in any official Fedora documentation must adhere to these guidelines:
|Software must be available in the official Fedora software repositories for the release of Fedora to which the documentation applies.|
|Software installation must be done via Fedora software management tools, preferably `yum`. If you document using GUI tools for package installation and management, cover the default application (`pirut`) before others, and cover it consistently.|
|Software must not require user compilation from source, or rebuilding from source RPMs.|
|Guides must not encourage reconfiguration of file system resources, security contexts, or any other resources from a software package that conflict with the intention of the maintainer for that software package.|
#### A.4.2.2. Administration Tools {#sect-documentation_guide-style-fedora_specific-general_conventions-administration_tools}
Guides must use the following conventions for system administration:
|Neither assume, nor configure, `sudo` rights. Use the following command instead:**su -c "<COMMAND>"**|
|To configure the current or persistent activation of services through initscripts, use the `/sbin/chkconfig` and `/sbin/service` binaries.|
### A.4.3. DocBook XML {#sect-documentation_guide-style-fedora_specific-DocBook_XML}
The preferred format for long-term maintenance of documents is DocBook XML. This format stores contextual style information without concern for document rendering and avoids common limitations of other document storage formats.
### A.4.4. Wiki {#sect-documentation_guide-style-fedora_specific-wiki}
Wiki markup is a structured form of plain text that is not as complex as DocBook XML and has become a popular format for new writing. The wiki format and the limited available markup are simple. Wiki is easy to read and edit in normal plain text editors. Unfortunately, it lacks the contextual markup that DocBook XML provides. The Fedora Project has adopted specific conventions to provide basic contextual support in the wiki format.
### A.4.5. ReST {#sect-documentation_guide-style-fedora_specific-ReST}
ReST is a lightweight structure form of plain text that can be used to produce meaningful XML output.
### A.4.6. Plain Text {#sect-documentation_guide-style-fedora_specific-plain_text}
Plain text documents contain no markup for style or context. They also lack any inherent structure. Original writing in plain text generally requires revision, including the addition of markup, before publication. A plain text document that uses wiki conventions and markup is easier to translate into wiki format, and using those conventions can improve the readability and structure of the document.
### A.4.7. Other Formats {#sect-documentation_guide-style-fedora_specific-other_formats}
There are many other formats for text storage. Each may provide different features and drawbacks. If a specific structure is adhered to, the amount of effort required to convert documents between different formats can be minimized.
## A.5. Common Mistakes {#sect-documentation_guide-style-common_mistakes}
Writers, even experienced ones, frequently make some simple mistakes. Once writers develop correct usage into habits, they can avoid these mistakes.
### A.5.1. Spelling {#sect-documentation_guide-style-common_mistakes-spelling}
The following words appear in texts frequently and are often spelled incorrectly. This list does not include locale-specific differences in spelling.
|INCORRECT: dependant, dependancies|
|CORRECT: dependent, dependencies|
|INCORRECT: kernal|
|CORRECT: kernel|
|INCORRECT: seperate|
|CORRECT: separate|
### A.5.2. Grammar {#sect-documentation_guide-style-common_mistakes-grammar}
_A v. an_ - The choice of which article to use, 'a' or 'an', is made by the sound of the first letter of the word following the article. The 'a' is used when the initial sound is a consonant, the 'an' is used when the initial sound is a vowel. The word 'SSH' starts with the "ess" sound, so the 'an' is used.
One common confusion is with acronyms and abbreviations, because that can change how you pronounce something. For example, if 'URL' is pronounced "You arr ell," it is "a URL". If 'URL' is pronounced "Earl" ("Urrl"), it is "an URL."
References:
### A.5.3. Punctuation {#sect-documentation_guide-style-common_mistakes-punctuation}
Sentences using "which" or "that" to separate statements frequently contain mistakes in the usage of commas. An instance of "which" is preceded by a comma, which is often forgotten. Instances of "that" are often incorrectly preceded by a comma that should not be present. When in doubt, trust your ear. "Which" wants a pause before it and "that" does not.
Use a comma for serial lists before the last item, that is:
"Foo, bar, and baz."
... not ...
"Foo, bar and baz."
Without the final comma, it is hard to tell if the final item is a "bar" or a "bar and baz". (Writers and editors sometimes refer to this punctuation as a "Harvard comma" or "serial comma.")
### A.5.4. Constractions {#sect-documentation_guide-style-common_mistakes-contractions}
Avoid contractions in professional writing. They are rarely needed or desired, and they are a common source of errors. When using them, writers often make errors that include spelling, placement of apostrophes, and improper usage within a sentence. The first rule to remember about contractions is that the apostrophe should be placed where the last omission of letters occurs.
## A.6. Word usage, capitalization, and spelling {#sect-documentation_guide-style-word_usage}
### Symbols {#idm49857808}
%
: See percent.
24x7
:
3-D (n. or adj.)
:
### A {#idm85018768}
a.m.
: Lowercase with periods and a preceding space.
above
: Do not use to refer to information mentioned previously. When documents are converted to another format or layout, the information may no longer be _above._
acronyms
: Spell out acronyms or initialization before using them in text, e.g., _Embedded DevKit (EDK)._ Unless the acronym or initials stand for a proper noun, use sentence case for the spelled-out version, e.g., _central processing unit (CPU)._
To form the plural of an acronym, add a trailing, lowercase s with no apostrophe, e.g., ROMs, PINs.
affect
: When you affect something, it produces an effect.
alpha release
: Do not capitalize this, as in "the alpha release of Product Foo."
alternate
: Do not use this to mean _an alternative to something._ _Alternate_ is a verb that means to change between two states or options. As an adjective, it means every second (alternating) thing in a series. If you mean _another way or option,_ use _alternative._
and/or
: Avoid if possible. One or the other nearly always conveys the real meaning. If it doesn’t, try a structure like, _Have some bacon, eggs, or both._
applications
: When used as a proper name, use the capitalization of the product or project, such as GNUPro, Source-Navigator, and Red Hat Enterprise Linux. When used as a command, use lowercase as appropriate, such as _To start GCC, type gcc._
Note: _vi_ is always lowercase.
assure
: Assure suggests mental comfort. Example: _I assured my future father-in-law that I would eventually find a job._ Also see [ensure](#anchor-ensure) and [insure](#anchor-insure).
auto-detect
:
Autofs
:
### B {#idm94035376}
backport
:
back end (n.), back-end (adj.)
:
back up (v.), backup (n.), back-up (adj.)
:
backtrace
:
backward
: Avoid using _backwards_ unless you are stating that something has _backwards compatibility._
backwards compatibility
:
bandwidth
:
basically
: Do not use. For example, removing the word _basically_ in the following sentence strengthens it: _This is how it is basically done._
because
: Do not use _since_ to mean _because._ Use _because_ to refer to a reason. Use _since_ to refer to the passage of time.
below
: Do not use to refer to information mentioned _below._ When documents are converted to another format or layout, the information may no longer be _below._
BIOS
: Plural: BIOSes
big data
: Descriptive term, not a proper noun, so not capitalized.
bit rate
:
Boolean
:
boot disk
:
boot loader
:
Bps, bps
: Bits per second is abbreviated bps. Bytes per second is abbreviated Bps. Also see bandwidth.
Britain
: The language is English, and the place is the United Kingdom of Great Britain and Northern Ireland, aka the UK. Using Britain/British is usually wrong and to some implies a specific subjective statement about the state of Northern Ireland.
bug fix
:
built-in
:
bulleted lists
: Lists should always consist of more than two items. Use bullets for a list in which the order of items is unimportant. Use a numbered list only when the order is important, as in a series of steps.
### C {#idm50460720}
can/may
: Use _can_ to describe actions or conditions that are possible. Use _may_ only to describe situations where permission is being given.
cannot
:
canceled
:
capitalization
: If it’s not the official name of a real product or service, don’t capitalize it. Not even if it seems important. Capitalize only the first letter of the first word in headlines, titles, subtitles, and other call-out text.
cd or CD
: When referring to the change directory command, use cd. When referring to a compact disk, use _CD._ The plural is _CDs._
checkbox
:
chipset
:
ciphertext
:
client side (n.);, client-side (adj.);
:
cloud
: Use a lowercase _c_ when referring to cloud or cloud computing in a general sense.
combo-box
:
commas
: Use serial commas. A serial comma is the comma before the _and_ in a series of three or more items: _Item 1, item 2, and item 3._ Because in some cases it is necessary to use a serial comma to avoid confusion, it is best to always use it for consistency. An exception to this rule is in press releases, where it is traditional and preferred not to use serial commas.
comma-delimited (adj.)
:
command-driven (adj.)
:
command language, line, processor
:
contractions
: Avoid when writing policy manuals or other more formal types of manuals. Contractions may also cause problems for documents that are translated, so avoid them in global content.
control character
:
control key
: Use Ctrl instead, such as _To save the program, press Ctrl+Z._
control program
:
cross-site scripting
:
cross-platform
:
currency
: Use the following format: $1,500 USD, omitting _USD_ if it is clear that it is in US currency.
### D {#idm95019584}
daisy chain
:
dashes
: When possible, use em-dashes (—) with no space on either side. When full em-dashes aren’t available, use double-dashes with no spaces on either side--like this.
datacenter
:
data mirroring
:
data type
:
datasheet
:
debug
:
denial of service (DoS)
:
dialog box
:
different
: Use _different from_ rather than _different than_.”
disc, disk
: Compact disc, but diskette or hard disk.
double-click
:
downtime
: The period during which a server, service, or other resource is unavailable.
download
:
dual-boot
:
DVD writer
: Do not use DVD burner or CD burner (use CD writer in that case).
### E {#idm47367792}
e-book, e-business, e-commerce, e-learning
:
earlier
: See [later](#anchor-later).
Emacs
:
email
:
effect
: See [affect](#anchor-affect).
email
:
ensure
: Ensure means _to make sure._ See also [assure](#anchor-assure) and [insure](#anchor-insure).
essentially
: Do not use. See also [basically](#anchor-basically).
Ethernet
:
exclamation points (!)
: Do not use them at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command.
Exif
:
ext3
:
extranet
:
### F {#idm84802096}
failover (n.);, fail over (v.)
:
fault tolerance
:
Fedora™ Project
:
fiber
: Despite the alternative spelling used in Fibre Channel, _fiber_ is the correct form to use in all other cases.
Fibre Channel
:
file name
:
file system
:
FireWire
:
firmware
:
floating point
:
forward
: Avoid using _forwards._
front end (n.), front-end (adj.)
:
FTP
: Stands for file transfer protocol. You may actually need to refer to SFTP, secure file transfer protocol. Use lowercase when referring to the command-line program.
### G {#idm81716416}
g++, G++
: When referring to the command, use g++. When referring to the program, use G++.
gas, GAS
: When referring to the command, use gas. When referring to the program, use GAS.
GB
:
Gbps
:
gcc, GCC
: When referring to the command, use gcc. When referring to the program, use GCC.
gcj, GCJ
: When referring to the command, use gcj. When referring to the program, use GCJ.
gdb, GDB
: When referring to the command, use gdb. When referring to the program, use GDB.
gigabyte
: 2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. Abbreviated _GB._
GIMP (GNU Image Manipulation Program)
:
GNOME
:
GNU
: (GNU’s Not UNIX)
GNUPro
:
gray
:
GTK+
:
### H {#idm97276352}
hard-coded (adj.), hard code (v.)
:
hard copy
: Do not use. Instead, use _printed._
hard disk
:
hard drive
:
he/she
: Do not use. Reword to avoid.
high-availability (adj.), high availability (n.)
:
high-performance computing (HPC)
:
homepage
:
host group
:
hostname
: Capitalize when used at the beginning of a sentence, but try to reword the sentence to avoid this.
hot add
:
hot plug
:
hot swap
:
hotline
:
HTML
:
Hyper-Threading
:
hypervisor
:
Hz
: Also see [bandwidth](#anchor-bandwidth).
### I {#idm40023968}
I/O
:
i.e., e.g.
: i.e. means _in other words._ e.g. means _for example._ Add commas after each (e.g.,).
illegal
: Illegal means _prohibited by law,_ not _incorrect_ or _not permitted._ You may be looking for the word _invalid._
in concert with
: Do not use. Instead, simply say _with._
Infrastructure-as-a-Service (IaaS)
:
inline
:
insecure
: Do not use _nonsecure,_ _non-secure,_ or _unsecured._
installation program
: Do not use _installer._
insure
: _Insure_ relates to monetary insurance. Also see assure and ensure.
Intel 64
: Do not use _Hammer,_ _x86\_64,_ or _x86-64_ as the name of this architecture. The correct term for AMD’s implementation of this architecture is _AMD64._
interesting
: Avoid using, as this is a substitute for showing the reader why something is of interest. For example, change _It is interesting to note_ to _Note._
Internet
:
intranet
:
IP (Internet Protocol)
:
IPsec (Internet Protocol security)
:
is designed to
: Avoid this and similar phrases when describing a function.
Incorrect: SSH is designed to work with almost any kind of public key algorithm or encoding format.
Correct: SSH works with almost any kind of public key algorithm or encoding format.
### J {#idm42973216}
just
: Use sparingly and avoid when possible. For example, in a phrase like, _Just point your browser to,_ omit the word _just._
### K {#idm83574640}
KB
:
kbps
:
kernel space (n.), kernel-space (adj.)
:
kilobit, kilobyte
:
### L {#idm58311072}
later/newer
: When referring to more recent versions of a product, package, or other software, use _later._ When referring to earlier versions, use _earlier._
left-click
:
life cycle
:
Linux®
: Linux is a registered trademark of Linus Torvalds. It gets a registered trademark symbol on first use.
lists
: Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, etc.
Capitalize the first word of each bullet, unless it is obvious that it is just a list of items, such as a list of items like:
* computer
* monitor
* keyboard
When the bulleted list items complete a sentence or are sentences themselves, use periods on each item. If they do not, or are simply a list of items (like the list above), no periods are necessary.
log file
:
log in (v.), log-in (adj.), login (n.)
:
lookup (n.), look up (v.);, look-up (adj.)
:
LVM
:
### M {#idm52629280}
man page
:
mashup
:
may/can
: Use _can_ to describe actions or conditions that are possible. Use _may_ to describe situations where permission is being given.
MB, Mb
: MB is short for megabyte (1,000,000 or 1,048,576 bytes, depending on the context). Mb is short for megabit.
MBps
:
metadata
:
Microsoft
: Do not use _MS_, _MSFT_ or _MicroSoft._
months
: Abbreviate months and states according to AP. Months are abbreviated only if they are used in conjunction with a day. Example: _The President visited in January 1999._ or _The President visited Jan. 12._ Abbreviated months: Jan., Feb., March, April, May, June, July, Aug., Sept., Nov., Dec.
Mozilla Firefox
: Subsequent references can be _Firefox._
Mozilla Thunderbird
: Subsequent references can be _Thunderbird._
multi-
: Hyphenate words with the prefix _multi_ unless the dictionary or this guide says otherwise.
multiprocessing
:
MySQL
:
### N {#idm90770544}
nameserver
:
namespace
:
.NET
:
newer
:
non-
: Hyphenate words with the prefix _non_ unless the dictionary says otherwise.
nonsecure
: Use _insecure_ instead.
NULL, null
: When a command or value is stated, use NULL. When stating that something is null, use _null._
numbers
: Write out numbers between one and nine.
Exceptions:
* Beginning a sentence
* Preceding another number (four 6-pound bags)
* Approximations (_thousands of_)
* Very large values (4 billion)
* Ranges (4—6 datacenters)
Use numerals for numbers 10 and greater, negative numbers, fractions, percentages, decimals, measurements, references to book sections (Chapter 3, Table 5, Page 11), and numbers less than 10 if they appear with numbers of 10 or greater (_You answered 8 out of 14 questions correctly_). Also use numerals when referring to code (such as x = 6) and release versions (Fedora 20).
numbered lists
: Lists should always consist of more than two items. Use bullets for a list in which the order of items is unimportant. Use a numbered list only when the order is important, as in a series of steps.
### O {#idm44176048}
Objective C
:
object-oriented
:
OEM (original equipment manufacturer)
:
offline
:
online
:
on-site
: Hyphenated when used as an adjective, as in _on-site labs._
on demand (adv.), on-demand (adj.)
:
opcodes
:
open source
:
operating system
:
orientate
: Do not use. A user becomes _oriented_ to an environment.
over
: When referring to something quantifiable, use _more than_ instead.
override
:
### P {#idm61899552}
packet-switching
:
pc, PC
: When referring to program counter, use pc. The first instance must have the acronym defined, such as _program counter (pc)._ When referring to a general computer, use _PC._
percent (%)
: Use the percent sign (%) whenever referring to numerical percentages.
Example: In a survey, 60% of users said they were satisfied with their technology solution.
Exception: Press releases and press blogs follow strict AP style, which spells out 'percent' in all uses.
peer-to-peer architecture
:
Perl
:
plain text
:
Platform-as-a-Service (PaaS)
:
please
: Do not use. Instead of _Please refer to the Getting Started Guide,_ write, _Refer to the Getting Started Guide._
plug-in (n), plug in (v)
: As a noun, _plug-in_ is a hardware or software module that adds a specific feature or service to a larger system.
p.m.
: See [a.m.](#anchor-am)
pop-up
:
PostScript
:
PowerPC
: Do not use _PPC_ or variants.
PPP
:
proximity
: Don’t use _close proximity._ It’s redundant.
pseudo-ops
:
pulldown
:
### Q {#idm61552704}
quotations
: _Place the punctuation inside the quotes,_ said the editor. Except in rare instances, use only _said_ or _says_ for quotes. Other words liked _noted_ or _quipped_ get in the way of the quote itself and tend to editorialize.
Place _said_ first, followed by the name: _Friends, freedom, features, first,_ said Beefy Miracle.
### R {#idm42028352}
regardless
: _Irregardless_ is not a word.
read-only
:
read/write
:
real-time (adj.), real time (n)
:
reboot
:
recursive
:
Red Hat
: Write _Red Hat._ Not _Red Hat, Inc._ (The only exceptions to this rule are when the company itself is writing legal or financial statements.) _Red_ and _Hat_ should be on the same line together. Don’t let them be separated by a line break.
Pronoun and verb agreement: A company is singular in the US. In other words, Red Hat is an _it,_ not a _they._
right-click
:
roadmap
:
RPM
:
runlevel
:
runtime
:
### S {#idp449328}
screenshot
:
scrollbar
:
SELinux
:
server side (n.), server-side (adj.)
:
set up (v.), setup (n.), set-up (adj.)
:
sign up (verb), sign-up (noun, adjective)
:
shut down (v.),
:
simply
: Do not use. See [basically](#anchor-basically).
since
: See [because](#anchor-because).
smart card
:
soft copy
: Do not use.
Software-as-a-Service (SaaS)
:
sound card
:
space
: Use when referring to white space, such as _Ensure there is a space between each command._ Use _spacebar_ when referring to the keyboard key.
spaces (using),
: Use only one space between sentences. Use no spaces around an em-dash.
spec file
:
standalone
:
startup
:
states
: Use the two-letter postal abbreviations. See stateabbreviations.us for a list.
stovepipe
:
subdirectory
:
submenu
:
superuser
:
swap space
:
SysV
:
### T {#idm76170800}
taskbar
:
Telnet
:
that/which
: _That_ introduces a restrictive clause — a clause that must be there for the sentence to make sense. A restrictive clause often defines the noun or phrase preceding it.
_Which_ introduces a non-restrictive, parenthetical clause — a clause that could be omitted without affecting the meaning of the sentence. Use”who” or _whom,_ rather than _that_ or _which,_ when referring to a person.
For example: The car was travelling at a speed that would endanger lives. The car, which was travelling at a speed that would endanger lives, swerved onto the sidewalk.
that vs. who
: Use _that_ when referring to places and things, including groups (e.g., customers), teams, and companies. Use _who_ when referring to individual persons.
then/than
: _Then_ refers to a time in the past or the next step in a sequence.
_Than_ is used for comparisons.
third-party
:
this
: The word _this_ can be used as an adjective or a pronoun. If you use it as a pronoun, be clear what the antecedent is. If it is unclear, use the adjective form by following _this_ with a noun.
throughput
:
time zone
:
timeout
:
token-ring
:
toolbar
:
troubleshoot
:
### U {#idm93483680}
under
: When referring to something quantifiable, use _fewer than._
UNIX
: UNIX is a registered trademark of The Open Group. Do not use _UNIX-like._ Use an expression like _Linux, UNIX, and similar operating systems_ instead.
upgrade
:
URLs
: For URLs that begin with http://www., you may omit that portion and give the main URL, such as fedoraproject.org. If it begins with ftp or https, you should include the full URL.
US (adjective), United States (noun)
:
usable
:
userid
:
user interface
:
username
:
user space
:
utilize
: Avoid this term. Write _use_ instead.
### V {#idm51859680}
vi, Vim
:
virtualization
:
### W {#idm43196512}
Web 2.0
: Avoid using this term.
web, web browser, webmaster, web server, website
:
white space
:
whitepaper
:
workflow
:
worldwide
:
writable
:
### X {#idm61455392}
x86
:
Xen
:
X Window System
:
### Z {#idm61258496}
ZIP code
:
## A.7. Quick Reference {#sect-documentation_guide-style-quick_reference}
### A.7.1. Numbers {#sect-documentation_guide-style-quick_reference-numbers}
#### A.7.1.1. When to Spell Out a Number {#sect-documentation_guide-style-quick_reference-numbers-when}
Rules for using Arabic numerals or spelling out numbers are as follows and are listed from highest priority to lowest.
|If the number is part of a casual expression, spell it out.|
|If the number is a calendar year, do not spell it out.|
|If the number is an age or percentage, do not spell it out.|
|If the number begins a sentence, spell it out. Awkward sentences should be reformed.|
|If the number is greater than 10, do not spell it out.|
|If the number is one through nine, spell it out.|
#### A.7.1.2. When to use Roman numerals {#sect-documentation_guide-style-quick_reference-numbers-roman_numerals}
Use Roman numerals for wars and honorific suffixes.
|World War II|
|John Doe III|
#### A.7.1.3. Cardinal Numbers and Ordinal Numbers {#sect-documentation_guide-style-quick_reference-numbers-cardinal_numbers_and_ordinals_numbers}
Cardinal numbers include figures 1, 2, 10, 101, and so on, and the corresponding words.
Ordinal numbers include the terms 1st, 2nd, 10th, 101st, and so on, and the corresponding words.
#### A.7.1.4. Large Numbers {#sect-documentation_guide-style-quick_reference-numbers-large_numbers}
When spelling out large numbers, connect words ending in 'y' to subsequent words within the same number with a hyphen. Avoid commas between words that are part of one number.
|twenty-one|
|one hundred thirty-one|
|twenty-five thousand one hundred thirty-one|
|ninety bottles|
#### A.7.1.5. Proper Names {#sect-documentation_guide-style-quick_reference-numbers-proper_names}
Write proper names according to the owner's practice.
### A.7.2. Abbreviations {#sect-documentation_guide-style-quick_reference-abbreviations}
#### A.7.2.1. The United States {#sect-documentation_guide-style-quick_reference-abbreviations-United_States}
As a noun appearing alone, use "United States."
: ...the government of the United States...
As a noun appearing as part of a locality, use "US" with no periods and no spaces.
: Raleigh, NC, US
As an adjective, use "U.S." with no spaces.
: ...the U.S. government...
##### A.7.2.1.1. States {#sect-documentation_guide-style-quick_reference-abbreviations-United_States-states}
Spell out state names when they appear alone.
: ...the government of North Carolina...
When abbreviating state names, use their two-letter ZIP standard abbreviations., Abbreviate state names when they appear as part of a locality.
: Raleigh, NC
Place one comma between the city and state name and another after the state name, unless it ends the sentence or is part of a dateline.
: ...founded in Raleigh, NC, by Red Hat...
...managed from Raleigh, NC.
#### A.7.2.2. Academic Degrees {#sect-documentation_guide-style-quick_reference-abbreviations-academic_degrees}
|Avoid abbreviating degrees.|
|Use an apostrophe in bachelor's degree, master's, etc.|
|Do not use an apostrophe in Bachelor of Arts, Master of Science, etc.|
|Use abbreviations only when the preferred method would be cumbersome.|
|Use abbreviations only after a full name.|
|Set abbreviations apart with commas.|
#### A.7.2.3. Dates {#sect-documentation_guide-style-quick_reference-abbreviations-dates}
|Spell out days of the week and separate them from dates using a comma.|
|When listing a day, month and year, use ISO 8601 dates (YYYY-MM-DD). Read more about dates and times on the [DatesAndTimes](http://fedoraproject.org/wiki/DocsProject/StyleGuide/DatesAndTimes) page.|
When listing a day and month:
|List the day first.|
|Spell out the day.|
|Set the day and month apart with "of."|
|Spell out the month.|
When listing a month and year:
|List the month first.|
|Spell out the month.|
|Set the month and year apart with "of."|
|Use Arabic numerals for the year.|
Sunday, 2000-01-01
2000-01-01
The first of January
January of 2000
#### A.7.2.4. Times {#sect-documentation_guide-style-quick_reference-abbreviations-times}
|Use 24-hour time formats.|
|Always use figures.|
|Follow absolute times with a timezone specification.|
|Separate days, hours, minutes and seconds with a colon and no spaces.|
|Separate seconds and fractions thereof with periods.|
|If the scope of a specification is unclear, increase the precision or specify the scope of the lowest precision.|
|Use Coordinated Universal Time (UTC) for all worldwide events. Refer to the [Section A.3.1.2, “Absolute Times”](#sect-documentation_guide-style-dates_and_times-absolute_dates_and_times-absolute_times "A.3.1.2. Absolute Times") section for more information about UTC.|
|Localized events may be specified using UTC or the local time, but always specify a timezone or offset.|
15:00 UTC
1:15:00:00.50 (1 day, 15 hours, 0 minutes, 0 seconds and 50/100 of one second)
15:00 minutes (15 minutes)
15:30 hours (15 hours and 30 minutes)
The global conference will take place at 15:00 UTC.
The event will be in Raleigh, NC, and will take place at 11:00 UTC-4.
### A.7.3. Punctuation {#sect-documentation_guide-style-quick_reference-punctuation}
#### A.7.3.1. Commas {#sect-documentation_guide-style-quick_reference-punctuation-commas}
For consistency and to avoid ambiguity, use a serial comma after every item in a list save the last. This usage is sometimes called the "Harvard comma" or the "Oxford comma."
spam, spam, spam, and eggs
Do not use a serial comma in the name of companies such as law firms.
Dewey, Cheatam & Howe
### A.7.4. Lists {#sect-documentation_guide-style-quick_reference-lists}
|Capitalize and use periods when the list items are complete sentences.|
|Make them agree so that there aren't a mixture of sentences and fragments.|
You could also have a list with a colon:
|that was lowercase and not punctuated|
|that again doesn't mix forms|
|that is likely very short|
### A.7.5. Titles {#sect-documentation_guide-style-quick_reference-titles}
|Avoid punctuation in titles, with the exception of hyphens.|
|Avoid abbreviations in titles. Spell words out and introduce abbreviations in the body text.|
### A.7.6. Units of Measure {#sect-documentation_guide-style-quick_reference-units_of_measure}
|Metric units are preferred.|
|Use the prefixes published by the International Electrotechnical Commission (IEC) as part of IEC 60027-2 A.2 to express quantities of binary data.|
### A.7.7. Common Technology Terms {#sect-documentation_guide-style-quick_reference-common_technology_terms}
|cyberspace|
|database|
|dot-com|
|DSL|
|email|
|FLOSS (free/libre open source software)|
|home page|
|hyperlink|
|hypertext|
|Internet|
|intranet|
|log in (intransitive verb)|
|log into|
|login (noun)|
|online|
|shareware|
|Web (proper noun)|
|webcast|
|webmaster|
|website|
|World Wide Web|
### A.7.8. Denoting trademarks {#sect-documentation_guide-style-quick_reference-denoting_trademarks}
Never use the trademark symbol (™) or the registration mark (®). If for any reason the Fedora Project is obliged by contract to mention other trademarks in a legend, add the legend as required by the contract.
In addition, all documentation should contain the disclaimer: "All other trademarks are the property of their respective owners." This marking is standard in all Fedora Documentation toolchains at the time of this writing.
## A.8. Resources {#sect-documentation_guide-style-resources}
### A.8.1. Useful FLOSS Project Guides {#sect-documentation_guide-style-resources-FLOSS}
|[GNOME Documentation Style Guide](http://library.gnome.org/devel/gdp-style-guide/stable/)|
### A.8.2. Other Style Guides {#sect-documentation_guide-style-resources-other_style_guides}
|[The Associated Press](http://www.ap.org)|
|[The Chicago Manual of Style](http://www.chicagomanualofstyle.org)|
|[Wikipedia article on style guides](http://en.wikipedia.org/wiki/Style_guide)|
### A.8.3. US-English Grammar {#sect-documentation_guide-style-resources-grammar}
|[The Blue Book of Grammar and Punctuation](http://www.grammarbook.com/grammar/subjectVerb.asp) provides examples of common difficulties encountered when writing in English. The Table of Contents covers "Who and Whom", "Who vs. Which vs. That" to "Effective Writing". Provides useful and clear examples with memorable tools.|
### A.8.4. Standards {#sect-documentation_guide-style-resources-standards}
|[Wikipedia article on ISO-8601](http://en.wikipedia.org/wiki/ISO_8601), "Data elements and interchange formats -- Information interchange -- Representation of dates and times"|
|[Wikipedia article on Coordinated Universal Time](http://en.wikipedia.org/wiki/UTC)|
|[Wikipedia article on binary prefixes](Wikipedia article on Coordinated Universal Time)|
### A.8.5. DocBook {#sect-documentation_guide-style-resources-DocBook}
|[Documentation for DocBook](http://www.docbook.org)|
### A.8.6. Other Resources {#sect-documentation_guide-style-resources-other}
|[Merriam-Webster Online](http://www.m-w.com)|
# Appendix B. Revision History {#appe-documentation-guide-Revision_History}
|**Revision History**|
|Revision 0.4-1|Sat Mar 22 2014|Eric Christensen|
||Added style guide.||
|Revision 0.3-1|Mon May 28 2012|Ben Cotton|
||Added a publican troubleshooting note.|
|Updated the lang\_map.||
|Revision 0.2-1|Thu Sep 15 2011|Petr Kovář|
||Moved Translations instructions from Fedora Wiki to Translations chapter.||
|Revision 0.1-1|Mon Jun 13 2011|Eric Christensen|
||Moved Publican instructions from Fedora Wiki to Publican chapter.||
|Revision 0.0-0|Sun Jun 12 2011|Jared Smith|
||Initial creation of book by publican|
|Created initial framework||
# Index {#idm4346496}
### F
feedback
: contact information for this manual, [We want feedback](#idm60858352)
### I
IRC (Internet Relay Chat)
: communicating with the Docs team, [Tips for Success](#idm50697184)
### M
mailing list
: communicating with the Docs team, [Tips for Success](#idm50697184)