copy-editing chapter 10.

[ardour-manual] / STYLE_GUIDE

diff --git a/STYLE_GUIDE b/STYLE_GUIDE
index 278c65a0d4bd1860480b3f19fb9a72a28dc544f1..001b2a72c65b23041400ab5aebe7d9c36e04b035 100644 (file)
--- a/STYLE_GUIDE
+++ b/STYLE_GUIDE
@@ -270,3 +270,27 @@ https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capit
 * Do not capitalize concepts in the text body, with the possible exceptions
   of _the_ Editor and _the_ Mixer.
 
+
+5.4 Janitorial tasks/review
+---------------------------
+
+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.