[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