[gnome-terminal/wip/mallard-merge: 10/289] help: review

[Ekaterina Gerasimova <egerasimov src gnome org>]

commit 3c03fbc77f8bd3c9e9de00fe91ff3ed67c8aa815
Author: Ekaterina Gerasimova <kittykat3756 gmail com>
Date:   Wed Jan 9 17:36:35 2013 +0000

    help: review

 help/C/colors-basic.page         |    4 ++++
 help/C/introduction.page         |   35 +++++++++++++++++++++--------------
 help/C/tabbed-terminals.page     |    4 ++++
 help/C/terminal-environment.page |    2 +-
 help/C/title-command.page        |    4 +++-
 5 files changed, 33 insertions(+), 16 deletions(-)
---
diff --git a/help/C/colors-basic.page b/help/C/colors-basic.page
index 4287a66..6f8d545 100644
--- a/help/C/colors-basic.page
+++ b/help/C/colors-basic.page
@@ -17,6 +17,10 @@
 
   <title>Colors</title>
 
+<!-- How is this page different from colors-custom? You will need to be more
+     specific when it comes to writing it. You've got the page naming scheme
+     pinned down here. -->
+
   <p></p>
 
 </page>
diff --git a/help/C/introduction.page b/help/C/introduction.page
index 6b4613f..e35dc43 100644
--- a/help/C/introduction.page
+++ b/help/C/introduction.page
@@ -18,24 +18,31 @@
     <link type="guide" xref="index"/>
 
     <desc>Introduction to <app>Terminal</app></desc>
+<!-- Try not to use the same terms in the title and description. For example,
+     the description would be better as "What is a terminal?". That would also
+     be more consistent with the desired tone (I will elaborate by email). -->
   </info>
 
   <title>Introduction</title>
 
-  <p><app>Terminal</app> is a terminal emulator application to
-  access a UNIX shell environment and run programs available on your system.
-  <app>Terminal</app> emulates xterm which supports escape sequences
-  that control cursor position and colors.</p>
+  <p><app>Terminal</app> is a terminal emulator application for accessing a
+  UNIX shell environment that can be used to run programs which are available
+  on your system. <app>Terminal</app> emulates xterm which supports escape
+  sequences that control cursor position and colors.</p>
+<!-- In this context, xterm is an application type, not the application. We
+     need to try making this clear as there is potential for confusion here,
+     especially for our target audience who are likely to not know what we're
+     talking about here. -->
 
-    <table>
-      <tr>
-       <td>
-        <media type="image" src="figures/gnome-terminal.png" width="700">
-          <p>Screenshot of GNOME <app>Terminal</app></p>
-        </media>
-       </td>
-      </tr>
-      <tr><td><p><em>GNOME Terminal</em></p></td></tr>
-   </table>
+  <figure>
+    <desc>GNOME Terminal</desc>
+    <media type="image" src="figures/gnome-terminal.png" width="700">
+      <p>Screenshot of GNOME <app>Terminal</app></p>
+    </media>
+  </figure>
+<!-- Images should not be in a table unless they *have* to be. Also indent the
+     first element in situations like this as you would a paragraph. See
+     http://projectmallard.org/about/learn/media.html#figures - note that the order
+     of the tags inside <figure> matters!-->
 
 </page>
diff --git a/help/C/tabbed-terminals.page b/help/C/tabbed-terminals.page
index 235022d..ed1e3a6 100644
--- a/help/C/tabbed-terminals.page
+++ b/help/C/tabbed-terminals.page
@@ -1,6 +1,8 @@
 <page xmlns="http://projectmallard.org/1.0/";
       type="guide"
       id="tab-terminals">
+<!-- If this page is going to be about *windows* and tabs, then the ID should
+     reflect this. Try to match page file names to IDs. -->
 
   <info>
     <revision version="0.1" date="2013-01-09" status="draft"/>
@@ -16,6 +18,8 @@
   </info>
 
   <title>Mutiple Terminals</title>
+<!-- Try to improve this title when you come to this page, I think it can be
+     better. Also, use "Multiple <app>Terminals</app>" or "Multiple terminals". -->
 
   <p></p>
 
diff --git a/help/C/terminal-environment.page b/help/C/terminal-environment.page
index 745a857..999ee7b 100644
--- a/help/C/terminal-environment.page
+++ b/help/C/terminal-environment.page
@@ -15,7 +15,7 @@
     <desc>Understanding your terminal</desc>
   </info>
 
-  <title>Terminal Environement</title>
+  <title>The terminal environement</title>
 
   <p></p>
 
diff --git a/help/C/title-command.page b/help/C/title-command.page
index 185aa53..c9baff3 100644
--- a/help/C/title-command.page
+++ b/help/C/title-command.page
@@ -13,9 +13,11 @@
     </credit>
 
     <desc>How to set terminal title and run custom commands on startup</desc>
+<!-- On face value, these seem like two independent tasks. If they turn out to
+     be when you write them, then consider spliting into two pages. -->
   </info>
 
-  <title>Title and Command</title>
+  <title>Title and command</title>
 
   <p></p>