[documentation-guide] Moving some cheese here. The sections are really short and by the time I'm done adding stuff, there

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


commit 9a19850cc223885ac7302662e072721e47b0a9f9
Author: Ben Cotton <bcotton at fedoraproject.org>
Date:   Mon May 28 23:19:09 2012 -0400

    Moving some cheese here. The sections are really short and by the time
    I'm done adding stuff, there will be a lot of sections in this chapter.
    So I'm just going to condense all of these into a single section. Feel
    free to yell at me later if you like.

 en-US/style.xml |   48 +++++++++++++++++-------------------------------
 1 files changed, 17 insertions(+), 31 deletions(-)
---
diff --git a/en-US/style.xml b/en-US/style.xml
index 9c0143b..8cda2ff 100644
--- a/en-US/style.xml
+++ b/en-US/style.xml
@@ -6,52 +6,38 @@
 <chapter id="chap-documentation_guide-style">
 	<title>Style Guide</title>
 	<para>
-		Your writing should be styled consistently and concisely. This section will outline 
+		Your writing should be styled consistently and concisely. This section outlines
 		style conventions to be used when writing documentation.
 	</para>
-		<section id="sect-documentation_guide-style-be_direct">
-		<title>Be Direct</title>
+	
+	<section id="sect-documentation_guide-style-tips">
+		<title>General tips</title>
 		<para>
-			Get straight to the point. Embellishments used in spoken language do not add value to a technical document.
+			Be direct. Embellishments used in spoken language do not add value to a technical document.
 			Be sparing with qualifiers like "usually," "should," and "often." 
-			The progression of the document will be apparent, avoid narrative language such as 
+			The progression of the document will be apparent. Avoid narrative language such as 
 			"now that we have configured with the file, we are going to issue a command." 
 		</para>
-	</section>	
-	<section id="sect-documentation_guide-style-be_concise">		
-		<title>Be Concise</title>
 		<para>
-			Don't use bromides and frivolous clauses.
+			Be concise. Don't use bromides and frivolous clauses.
 		</para>
-	</section>
-	<section id="sect-documentation_guide-style-be_professional">
-		<title>Be Professional</title>
 		<para>
-			Keep your writing relevant and impersonal.  Don't refer to the writer in the first person with 
+			Be professional. Keep your writing relevant and impersonal.  Don't refer to the writer in the first person with 
 			"I," "we," or "us," or the reader in the third person singular.  Using "you" is acceptable when 
 			giving instructions, but should be avoided in any statement of fact. "You" is preferred to the
 			gender-specific "he" or "she," the awkward "he or she," the ugly "s/he," and the excessively dry "one."
 		</para>
-	</section>
-	<section id="sect-documentation_guide-style-be_accurate">
-		<title>Be Accurate</title>
 		<para>
-			Use clear, contextually appropriate language.
+			Be accurate. Use clear, contextually appropriate language.
 		</para>	
-	</section>
-	<section id="sect-documentation_guide-style-stay_in_scope">
-		<title>Stay in Scope</title>
-			<para>
-				Your tips should adequately cover a stock installation of Fedora, in the present version. 
-				Consider a separate section or referring to another document if elaboration is required.  
-				Excessive asides will dilute the value of your work and create redundancies.
-			</para>
-	</section>
-	<section id="sect-documentation_guide-style-proofread">
-		<title>Proofread</title>
-			<para>
-				Review for spelling mistakes and grammar abuse. Remove contractions, which cause translation problems.
-			</para>
+		<para>
+			Stay in scope. Your tips should adequately cover a stock installation of Fedora, in the present version. 
+			Consider a separate section or referring to another document if elaboration is required.  
+			Excessive asides will dilute the value of your work and create redundancies.
+		</para>
+		<para>
+			Proofread. Review for spelling mistakes and grammar abuse. Remove contractions, which cause translation problems.
+		</para>
 	</section>
 	<section id="sect-documentation_guide-style-abbreviations">
 		<title>Abbreviations, acronyms, and initialisms</title>


More information about the docs-commits mailing list