[documentation-guide] Add software section (from wiki), image section, and shortened word section

Ben Cotton bcotton at fedoraproject.org
Tue May 29 03:21:17 UTC 2012


commit 093e3bd5f27d07b008bfc5c39dd90c2ad8ae0359
Author: Ben Cotton <bcotton at fedoraproject.org>
Date:   Mon May 28 22:53:10 2012 -0400

    Add software section (from wiki), image section, and shortened word
    section

 en-US/style.xml |   40 +++++++++++++++++++++++++++++++++++++++-
 1 files changed, 39 insertions(+), 1 deletions(-)
---
diff --git a/en-US/style.xml b/en-US/style.xml
index 8ecc4c4..9c0143b 100644
--- a/en-US/style.xml
+++ b/en-US/style.xml
@@ -53,4 +53,42 @@
 				Review for spelling mistakes and grammar abuse. Remove contractions, which cause translation problems.
 			</para>
 	</section>
-</chapter>
\ No newline at end of file
+	<section id="sect-documentation_guide-style-abbreviations">
+		<title>Abbreviations, acronyms, and initialisms</title>
+		<para>
+			When used appropriately, abbreviations, acronyms, and initialisms (for example: abbr., NASA, and UTC)
+			improve the flow of reading by providing brevity. The first use of the represented text should be
+			the full version, with the appropriate shortening in subsequent uses. If the use of the shortened form
+			of a word is ambiguious in context, rewrite or use the long form.
+		</para>
+	</section>
+	<section id="sect-documentation_guide-style-pictures">
+		<title>Pictures and screen captures</title>
+		<para>
+			The use of pictures and screen captures should be avoided whenever possible. Although they can be of aid
+			to users, trivial differences in appearance (e.g. desktop customizations) can be distracting or confusing.
+			In addition, the text that appears in an image is not easily translatable, so translators must generate their
+			own image. If you are tempted to use an image, consider improving your text to better describe the instructions.
+		</para>
+	</section>
+	<section id="sect-documentation_guide-style-software">
+		<title>Software</title>
+		<para>
+			Software that appears in any official Fedora documentation must adhere to these guidelines:
+		</para>
+		<simplelist>
+			<member>Software must be available in the official Fedora software repositories for the release of Fedora to
+				which the documentation applies.
+			</member>
+			<member>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 before
+				others, and cover it consistently.
+			</member>
+			<member>Software must not require user compilation from source, or rebuilding from source RPMs.
+			</member>
+			<member>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 package. 
+			</member>
+		</simplelist>
+	</section>
+</chapter>


More information about the docs-commits mailing list