X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=001b2a72c65b23041400ab5aebe7d9c36e04b035;hb=b386ec9a704966da7db41c2a1db1d9d4d20fe0ed;hp=4c57d00ca94a9d487a505adb974278858c78e1e6;hpb=2e006d9b931807ddc386650766de3a5fe44a271b;p=ardour-manual-diverged diff --git a/STYLE_GUIDE b/STYLE_GUIDE index 4c57d00..001b2a7 100644 --- a/STYLE_GUIDE +++ b/STYLE_GUIDE @@ -175,8 +175,9 @@ elements. ------------------------------------ -Any keys or key combinations, mouse buttons, or controllers should be marked -with this element. +Any keys or key combinations, mouse buttons or controllers, menu items or +textual user input should be marked with this element. It is used here in +the widest possible sense, qualified by classes. E.g.: "Press F to fit all tracks to the height of the Editor window." "Move Fader 1 on your MIDI controller to bind it. @@ -269,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

editorial note

, 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 (Via +the context menu,...Via hotkeys). 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.