X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=001b2a72c65b23041400ab5aebe7d9c36e04b035;hb=f02da197254664513d0ec548140352c764af0782;hp=7d2dad4ee7db2489a6d13d079d13917bb792c442;hpb=4c1590e505f3c47ef0f2783f64dc074338a82f17;p=ardour-manual

diff --git a/STYLE_GUIDE b/STYLE_GUIDE
index 7d2dad4..001b2a7 100644
--- a/STYLE_GUIDE
+++ b/STYLE_GUIDE
@@ -278,3 +278,19 @@ If you encounter something that is unclear or patent nonsense, but you are
 not bold or knowledgeable to fix it, express your doubts with an <p
 class="fixme">editorial note</p>, so that readers will be warned and fellow
 editors know where there's work to do.
+
+5.5 Writing style suggestions
+-----------------------------
+
+* "Click OK" and similar explanations of the utterly obvious should be
+avoided. Keep the writing concise and to the point. Explain as much as
+possible, with as few words as possible.
+* Do not fear repetitions, this is not artistic prose. Repeat important 
+keywords, rather than burden the user with synonyms made up on the spot.
+* Do not create headings for different ways of doing the same thing (<h>Via
+the context menu</h>,...<h>Via hotkeys</h>). Headings separate new
+concepts. To not add gratuitous sub-headings if there is very little 
+content per heading and you do not expect the article to grow.
+* If pages grow long, consider splitting them into sub-chapters at their
+headings.
+* Nobody needs "the next paragraph is about the following" paragraphs.