GNOME.org
 

[gnome-devel-docs] Created stubs and a few draft pages for the new Style Guide

commit 4d53eb3977412d94fe11d3dbe5e70c3b7a083c37
Author: Phil Bull <philbull gmail com>
Date:   Thu Dec 23 17:10:17 2010 +0000

    Created stubs and a few draft pages for the new Style Guide

 style-guide/index.page                      |   29 ++++++++++
 style-guide/style-language-conventions.page |   22 +++++++
 style-guide/style-principles.page           |   81 +++++++++++++++++++++++++++
 style-guide/style-tone.page                 |   56 ++++++++++++++++++
 style-guide/terms-complete.page             |   22 +++++++
 style-guide/terms-desktop.page              |   24 ++++++++
 style-guide/terms-interactions.page         |   40 +++++++++++++
 style-guide/terms-objects.page              |   35 ++++++++++++
 style-guide/terms-principles.page           |   54 ++++++++++++++++++
 style-guide/terms-widgets.page              |   50 ++++++++++++++++
 10 files changed, 413 insertions(+), 0 deletions(-)
---
diff --git a/style-guide/index.page b/style-guide/index.page
new file mode 100644
index 0000000..8746295
--- /dev/null
+++ b/style-guide/index.page
@@ -0,0 +1,29 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="guide"
+      id="index">
+
+  <info>
+  
+    <desc>Guidelines for writers for the GNOME platform.</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-23" status="stub"/>
+    
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Style and Terminology</title>
+
+
+<section id="style">
+ <title>Writing Style</title>
+</section>
+
+<section id="terms" style="2column">
+ <title>Terminology</title>
+</section>
+
+</page>
diff --git a/style-guide/style-language-conventions.page b/style-guide/style-language-conventions.page
new file mode 100644
index 0000000..c676e64
--- /dev/null
+++ b/style-guide/style-language-conventions.page
@@ -0,0 +1,22 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="style-language-conventions">
+
+  <info>
+  
+    <link type="guide" xref="index#style"/>
+    
+    <desc>How you should construct sentences.</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-23" status="stub"/>
+    
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Language Conventions</title>
+
+</page>
diff --git a/style-guide/style-principles.page b/style-guide/style-principles.page
new file mode 100644
index 0000000..bcd1643
--- /dev/null
+++ b/style-guide/style-principles.page
@@ -0,0 +1,81 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="style-principles">
+
+  <info>
+  
+    <link type="guide" xref="index#style"/>
+    
+    <desc>Guiding principles for writing documentation.</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-23" status="draft"/>
+    
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Style Principles</title>
+
+ <quote>
+  <cite>Henry David Thoreau</cite>
+  <p>Our life is frittered away by detail.... Simplify, simplify.</p>
+ </quote>
+ 
+ <quote>
+  <cite><em>The Elements of Style</em>, William Strunck Jr. and E. B. White</cite>
+  <p>Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he should avoid all detail and treat his subjects only in outline, but that every sentence tell.</p>
+ </quote>
+ 
+ <quote>
+  <cite>Thomas Mann</cite>
+  <p>A writer is someone for whom writing is more difficult than it is for other people.</p>
+ </quote>
+ 
+ <quote>
+  <cite>John Ruskin</cite>
+  <p>Say all you have to say in the fewest possible words, or your reader will be sure to skip them; and in the plainest possible words or he will certainly misunderstand them.</p>
+ </quote>
+ 
+<section id="human">
+ <title>You are human, and so are your readers</title>
+ <p>There is a tendency in technical writing to be formulaic, to rely on using the same structures again and again. This makes your writing boring and unsatisfying. Avoid this at all costs - readers won't take the information on board as effectively if they are bored, and you won't be getting the satisfaction of exercising your creativity.</p>
+ <p>Having said that, you're not writing a novel. "Pleasant to read" is enough - don't obscure the content by desperately trying to work something interesting in there. Some topics are genuinely dull.</p>
+</section>
+
+<section id="simple">
+ <title>Write simply</title>
+ <p>Write in a way that is easy for your audience to understand. This shouldn't imply that you're writing for an unintelligent audience; rather, you're trying to save your readers unnecessary mental overhead. Simple writing is easier to understand, and the point of our technical writing is to help people to understand things.</p>
+ <p>"Simple" also means "non-technical". Use words that the reader will understand and know about, or at least be able to correctly guess the meaning of. Just because a word is widely used in the computer industry doesn't mean that real users will know what it means.</p>
+</section>
+
+<section id="direct">
+ <title>Be direct</title>
+ <p>Write directly to your reader. It's fine to use "you" and "your" - there is no need to always write abstractly, or for the third person. That doesn't mean that every sentence should be addressed directly to the reader, though.</p>
+ <p>Being direct also means cutting out waffle. Don't labor points (unless it's important to do so), don't over-describe things, and don't waste the user's time with introductory text. The most important information should go first - defer asides until later on.</p>
+ <p>Prefer shorter sentences with fewer clauses, but keep your writing friendly and natural. Being a little terse is OK as long as the text flows well.</p>
+ <p>You should also refrain from using flowery or excessively exuberant language. Trying to write in a poetic or learned manner can obscure the meaning of the content; too much enthusiasm can be offputting or patronizing.</p>
+</section>
+
+<section id="sufficient">
+ <title>Sufficient is better than complete</title>
+ <p>Write enough that the reader know what you are talking about, but not much more. There is a tendency to over-explain things in documentation, usually for reasons of completeness. It's OK to miss out bits of a topic that aren't as important or interesting. You can skim over steps that are obvious.</p>
+ <p>Likewise, your choice of topics shouldn't be dictated by completeness. Do users really need a topic on starting or exiting your app? Or would it be sufficient to leave those topics out?</p>
+</section>
+
+<section id="useful">
+ <title>Be useful</title>
+ <p>What you write should be useful to the reader. Writing about something simply because you <em>feel you should</em> isn't good enough; you'll end up with lazy, uninformative writing that doesn't answer your reader's questions.</p>
+ <p>Always think about what your intended readership is looking for before you start writing. This will help you to write something that gets straight to the heart of the matter, and fast. And if you can't think of anything that a reader might want to know about a topic, perhaps you don't really need to write that topic after all?</p>
+</section>
+
+<section id="rules">
+ <title>Break rules if it makes for better writing</title>
+ <p>Dogged adherence to rules can lead to awkward-sounding text. If it makes more sense to say something in a particular way, even if it's <em>technically</em> wrong, you should say it anyway.</p>
+ <p>There is a difference <em>bad</em> grammar and <em>not-quite-correct</em> grammar, however. Avoid the former; the rules of grammar are there to help avoid ambiguity and other confusions (even if they're not perfect).</p>
+ <p>Likewise, absolute technical correctness is vehemently <em>not</em> the aim of our technical writing. It's fine to abuse terms if doing so would make your text more understandable for the reader.</p>
+</section>
+
+</page>
diff --git a/style-guide/style-tone.page b/style-guide/style-tone.page
new file mode 100644
index 0000000..7640781
--- /dev/null
+++ b/style-guide/style-tone.page
@@ -0,0 +1,56 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="style-tone">
+
+  <info>
+  
+    <link type="guide" xref="index#style"/>
+    
+    <desc>Writing in an appropriate tone will help readers relate to the text.</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-23" status="draft"/>
+    
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Tone</title>
+
+<p>The tone of a piece of writing affects the reader's attitude towards it. You want the reader to be receptive to your writing; don't alienate them. Here are some key words to help you set the tone of your writing:</p>
+
+<list>
+ <item>
+  <p>Casual; friendly; light.</p>
+  <p>Stuffy, overly-formal writing can bore people, but imposing your bubbly personality on people can grate. A happy medium can be found: try to sound helpful and approachable, but maintain a neutral mood.</p>
+ </item>
+ <item>
+  <p>Competent; knowledgeable; sensible; confident; honest.</p>
+  <p>Sound like you know what you are talking about. Avoid seeming biased or radical. The reader will trust that they are receiving useful, correct information.</p>
+ </item>
+ <item>
+  <p>Professional interest; weakly personal; genuine.</p>
+  <p>Make the reader feel like they are being personally addressed by your writing, but don't be overly-familiar or superficially friendly.</p>
+ </item>
+</list>
+
+<section id="examples">
+ <title>Examples</title>
+ <p>Here are some examples of writing in the tone we are aiming for.</p>
+ <quote>
+  <cite>Desktop Help</cite>
+  <p>Depending on your screen and screen resolution settings, the fonts displayed on your computer may need some adjustments. The text may look either too big, too small, or may even look fuzzy and/or distorted. To fix this, you will need to make changes to your font resolution settings. You can just change the resolution settings to suit your personal preference too.</p>
+ </quote>
+ <quote>
+  <cite>Empathy Help</cite>
+  <p>On some IRC networks, you can register your nickname with a service called NickServ. By sending special messages to NickServ, you can set your password and identify yourself. Some IRC chat rooms may not allow you to join without a registered nickname.</p>
+ </quote>
+ <quote>
+  <cite>Guitar Tuner developer tutorial</cite>
+  <p>This signal handler has two arguments: a pointer to the GtkWidget that called the function (in our case, always a GtkButton), and a pointer to some "user data" that you can define, but which we won't be using here. (You can set the user data by calling <code>gtk_builder_connect_signals</code>; it is normally used to pass a pointer to a data structure that you might need to access inside the signal handler.)</p>
+ </quote>
+</section>
+
+</page>
diff --git a/style-guide/terms-complete.page b/style-guide/terms-complete.page
new file mode 100644
index 0000000..46ad6e7
--- /dev/null
+++ b/style-guide/terms-complete.page
@@ -0,0 +1,22 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="terms-complete">
+
+  <info>
+  
+    <link type="guide" xref="index#terms"/>
+    
+    <desc>A complete list of terminology recommendations.</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-23" status="stub"/>
+    
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Complete list of terms</title>
+
+</page>
diff --git a/style-guide/terms-desktop.page b/style-guide/terms-desktop.page
new file mode 100644
index 0000000..1876ecd
--- /dev/null
+++ b/style-guide/terms-desktop.page
@@ -0,0 +1,24 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="terms-desktop">
+
+  <info>
+  
+    <link type="guide" xref="index#terms"/>
+    
+    <desc>Terms to be used when referring to the major components of the desktop environment.</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-23" status="stub"/>
+    
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Desktop components</title>
+
+<p>Workspaces, etc.</p>
+
+</page>
diff --git a/style-guide/terms-interactions.page b/style-guide/terms-interactions.page
new file mode 100644
index 0000000..d0abd25
--- /dev/null
+++ b/style-guide/terms-interactions.page
@@ -0,0 +1,40 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="terms-interactions">
+
+  <info>
+  
+    <link type="guide" xref="index#terms"/>
+    
+    <desc>How to describe the way the user interacts with the user interface.</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-23" status="incomplete"/>
+    
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Interactions</title>
+
+<section id="mouse-keyboard">
+ <title>Mouse and keyboard actions</title>
+ <p>Users should be able to distinguish between actions which they have to perform with the mouse or with the keyboard, respectively.</p>
+
+ <list> 
+  <item><p>To perform this action, click <gui>Apply</gui>.</p></item>
+  <item><p>To perform this action, press <key>Enter</key>.</p></item>
+ </list>
+
+ <p>This is unique for the user to decide whether he has to click a button in the UI or to press a key on his keyboard. Please don't use it as follows:</p>
+
+ <quote>
+  <p>To perform this action, press the <gui>Apply</gui> button.</p>
+ </quote>
+
+ <p>In fact, we cannot <em>press</em> a button. The physical process <em>to press</em> isn't adaptable to a virtual object. Instead, we <em>click</em> with the mouse or another pointing device.</p>
+</section>
+
+</page>
diff --git a/style-guide/terms-objects.page b/style-guide/terms-objects.page
new file mode 100644
index 0000000..3ca64e9
--- /dev/null
+++ b/style-guide/terms-objects.page
@@ -0,0 +1,35 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="terms-objects">
+
+  <info>
+  
+    <link type="guide" xref="index#terms"/>
+    
+    <desc>Terms for describing objects that the user encounters in the user interface, such as files and folders.</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-23" status="stub"/>
+    
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Objects in the UI</title>
+
+<terms>
+
+ <item>
+  <title>xxx</title>
+  <media type="image" mime="image/png" src="media/xxx.png">
+   <p>Examples of xxx.</p>
+  </media>
+  <p></p>
+ </item>
+
+</terms>
+
+
+</page>
diff --git a/style-guide/terms-principles.page b/style-guide/terms-principles.page
new file mode 100644
index 0000000..e849aa7
--- /dev/null
+++ b/style-guide/terms-principles.page
@@ -0,0 +1,54 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="terms-principles">
+
+  <info>
+  
+    <link type="guide" xref="index#terms"/>
+    
+    <desc>Some guiding principles to help you decide which terminology to use.</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-23" status="draft"/>
+    
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Choosing terminology</title>
+
+<p>Using poor or complicated terminology confuses and slows-down users. In general, avoiding jargon is a very good idea, even if this results in a less concise term being used to describe an object or concept. Here are some guidelines to help you choose terminology well:</p>
+
+<list>
+ <item>
+  <p>Simple</p>
+  <p>Use non-technical, simple language. Complicated and rarely-used words should be avoided. Terms that are well-known inside the computer industry, but not in everydaylife, should be used with caution.</p>
+ </item>
+ <item>
+  <p>Unambiguous</p>
+  <p>It should be obvious what a term refers to. Describe things rather than trying to assign a name to them if a sensible name isn't availble.</p>
+ </item>
+ <item>
+  <p>Recognizable</p>
+  <p>If at all possible, choose terms that users will be instantly familiar with. Everyday words are preferred.</p>
+ </item>
+ <item>
+  <p>Not overly-specific</p>
+  <p>If a general term is appropriate, use that instead of a set of more specific ones. Categorizing things can lead to ambiguity when you must decide how to refer to something which doesn't cleany fit into your pre-defined categories.</p>
+  <p>Categorizing objects which look or behave in very similar ways can also confuse the user, who may not understand the subtle distinction between the categories. There is no need to choose terms for different types of window, for example.</p>
+  <p>If you are defining a terminology guide for your project, think about what it is necessary to define and what can be left up to the writer. Consistency in terminology is important for readers, but specifying too much makes it difficult for writers to follow your guidelines.</p>
+ </item>
+ <item>
+  <p>Not necessarily correct</p>
+  <p>Technical correctness should not be your primary concern when choosing terminology. The important thing is describing something in a way which makes sense to users and doesn't cause confusion. It's OK to be a little bit wrong.</p>
+ </item>
+</list>
+
+<note>
+ <title>Ask real users</title>
+ <p>When deciding on what terminology to use, you should test it on real end-users. This will help to ensure that your choices are relevant, understandable and sensible.</p>
+</note>
+
+</page>
diff --git a/style-guide/terms-widgets.page b/style-guide/terms-widgets.page
new file mode 100644
index 0000000..3cb7ae0
--- /dev/null
+++ b/style-guide/terms-widgets.page
@@ -0,0 +1,50 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="terms-widgets">
+
+  <info>
+  
+    <link type="guide" xref="index#terms"/>
+    
+    <desc>The terms to use when referring to a widget in the user interface.</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-23" status="stub"/>
+    
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Widgets</title>
+
+<terms>
+
+ <item>
+  <title>Button</title>
+  <media type="image" mime="image/png" src="media/button.png">
+   <p>Examples of buttons.</p>
+  </media>
+  <p></p>
+ </item>
+ 
+ <item>
+  <title>List</title>
+  <media type="image" mime="image/png" src="media/list.png">
+   <p>Examples of lists.</p>
+  </media>
+  <p></p>
+ </item>
+ 
+ <item>
+  <title>Checkbox</title>
+  <media type="image" mime="image/png" src="media/checkbox.png">
+   <p>Examples of checkboxes.</p>
+  </media>
+  <p></p>
+ </item>
+
+</terms>
+
+</page>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]