[gnome-klotski/wip/mallard-help-merge: 10/35] Review help

[Ekaterina Gerasimova <egerasimov src gnome org>]

commit e328726b08ea1864efe5afb4949efcdeecf26848
Author: Sindhu S <sindhus live in>
Date:   Tue Jul 1 23:42:40 2014 +0530

    Review help
    
    Work on each page by removing my review comments and fixing as asked.
    Commit a single page in each commit.

 help/C/game-introduction.page |    2 ++
 help/C/index.page             |    3 ++-
 help/C/moves.page             |    1 +
 help/C/puzzles-moves.page     |    2 +-
 help/C/rules.page             |    7 +++++++
 help/C/scores.page            |    3 +++
 help/C/shortcuts.page         |    1 +
 help/C/start-game.page        |    6 ++++++
 8 files changed, 23 insertions(+), 2 deletions(-)
---
diff --git a/help/C/game-introduction.page b/help/C/game-introduction.page
index 0d8a2f6..f02bc62 100644
--- a/help/C/game-introduction.page
+++ b/help/C/game-introduction.page
@@ -22,5 +22,7 @@
   objective of the game is to move the patterned block to the area bordered by
   the green markers in the minimum number of moves. You can achieve this by
   sliding the blocks horizontally or vertically.</p>
+  <!-- Just this setence would be fine ...<app>Klotski</app> is a <app>GNOME</app> game. -->
+<!-- Perhaps a screenshot? If you can't take one now, do it right before the 3.14 release. Mark this is as a 
TODO -->
 
 </page>
diff --git a/help/C/index.page b/help/C/index.page
index 3a3696c..2d0b2ea 100644
--- a/help/C/index.page
+++ b/help/C/index.page
@@ -24,7 +24,8 @@
   <p>Slide blocks to solve the puzzle. You can visit
   <link xref="game-introduction">Game introduction</link> to know more about
   the game. Other help topics are grouped together into sections below.</p>
-
+  <!--"You can visit" doesn't sound right. Rephrase this sentence to say "To know more about the game, visit 
<link>..." -->
+  <!--Why does the introduction link appear again on the index? Fix it. -->
 
   <section id="play" style="2column">
     <title>Playing Klotski</title>
diff --git a/help/C/moves.page b/help/C/moves.page
index b6c5123..5ab0cea 100644
--- a/help/C/moves.page
+++ b/help/C/moves.page
@@ -26,6 +26,7 @@
 
   <section id="patterned-block-moves">
     <title>Goal piece moves</title>
+    <!-- Break the first sentence into two sentences. -->
       <p>The goal location may be positioned slightly off the board and the
       goal piece which is the patterned block is always permitted to move to
       it. However, no other blocks are permitted to move off the board</p>
diff --git a/help/C/puzzles-moves.page b/help/C/puzzles-moves.page
index 9c0778e..3e5a7e1 100644
--- a/help/C/puzzles-moves.page
+++ b/help/C/puzzles-moves.page
@@ -1,7 +1,7 @@
 <page xmlns="http://projectmallard.org/1.0/";
       type="topic"
       id="puzzles-moves">
-
+<!--Why do we need a separate page for this? merge it with puzzles.page -->
   <info>
     <link type="guide" xref="index#tips"/>
     <revision version="3.12" date="2014-05-24" status="review"/>
diff --git a/help/C/rules.page b/help/C/rules.page
index 8fcf97d..47f9840 100644
--- a/help/C/rules.page
+++ b/help/C/rules.page
@@ -20,20 +20,27 @@
 
   <p>You have to follow some rules while sliding the blocks in order to solve
   <app>Klotski</app>. The rules are listed below:</p>
+  <!--Saying "you have to" is a aggressive language for documentation. Rephrase this? To say "These are the 
rules to follow when sliding blocks..." -->
 
   <section id="move-block">
     <title>Move a block</title>
       <steps>
         <item><p>Click on the block to be moved.</p></item> 
+        <!--There would be no click on a touch screen interface if GNOME were to be used on it. Besides, 
Click and Drag is the action to make a move right? So combine first and second instruction to say something 
like "Click and drag and the desired block to a location of your choice on the board" -->
         <item><p>Move the block to the desired location with the help of
         mouse.</p></item>
+        <!--mouse? Bring out that checklist please. Doesn't it not say that all help instructions should be 
system agnostic? Rephrase this.-->
         <item><p>Click on the block again.</p></item>
+        <!--If you combine first and second instuctions, this one won't be required -->
       </steps>
   </section>
 
+
+<!-- This section should be placed first and then "Move a block" section. -->
  <section id="rules">
    <title>Rules to move a block</title>
      <list>
+      <!-- Language is a bit negative for documentation. Try to say something like "The green blocks and 
boundary blocks cannot be moved. A block cannot be moved over the green blocks. However, it is allowed to 
move a patterend block. Only a single step is allowed in one move.-->
        <item><p>You can not move the green blocks and the boundary
        blocks.</p></item>
        <item><p>You can not move over a block with the exception that the
diff --git a/help/C/scores.page b/help/C/scores.page
index da6bb33..cf01435 100644
--- a/help/C/scores.page
+++ b/help/C/scores.page
@@ -21,13 +21,16 @@
   <p>You can compare your performance by looking at the number of moves you
   took in solving each puzzle in the previous games. To view your number of
   moves:</p>
+  <!-- Rephrase, this language is commanding for documentation. Start with "To check your performance..." 
and keep the sentence simple. -->
     <steps>
       <item><p>Select <guiseq><gui style="menu">Klotski</gui>
       <gui style="menuitem">Scores</gui></guiseq>.</p></item>
       <item><p> The dialog will display the <gui>Only 18 steps</gui> puzzle by
       default, to view other puzzles, select them in the drop down menu at the
       top of the dialog.</p></item>
+      <!-- Simplify this. Say "The dialog by default displays scores of the "Only 18 Steps" puzzle, to 
view...". Do not say drop down menu or top of the dialog, you are using language to describe UI which is 
bound to change!, just menu is enough. In another sentence say "From the menu, select the puzzle whose scores 
you wish to see.-->
       <item><p>Click on <gui style="button">OK</gui> to close the scores dialog
       box.</p></item>
+      <!-- This is what I would write "Click on OK to close <gui>Scores<gui>" -->
     </steps>
 </page>
diff --git a/help/C/shortcuts.page b/help/C/shortcuts.page
index d0e2779..94b4c60 100644
--- a/help/C/shortcuts.page
+++ b/help/C/shortcuts.page
@@ -18,6 +18,7 @@
   <title>Keyboard shortcuts</title>
   <p>Some things can be done with a simple press of a key. Here are a few
   Keyboard shortcuts for <app>Klotski</app>:</p>
+  <!-- I like the language but sentence needs rephrasing, say something like "To access the game the game 
through keyboard, use the the following shortcuts:" -->
     <table frame="all" rules="cols" shade="rows">
       <tr>
         <td><p>New game</p></td>
diff --git a/help/C/start-game.page b/help/C/start-game.page
index aeba81f..56f763e 100644
--- a/help/C/start-game.page
+++ b/help/C/start-game.page
@@ -20,17 +20,23 @@
 
   <p><app>Klotski</app> offers you a large collection of games, to play a new
   game:</p>
+  <!-- No need to say "you" -->
     <steps>
       <item><p>Select <guiseq><gui style="menu">Klotski</gui>
       <gui style="menuitem">New Game</gui></guiseq> from the application menu.
+      <!--Don't describe the UI! Don't say "Application Menu", your mark up is enough to indicate that the 
user should go to App Menu -->
       Alternatively, you can click the <gui style="button">Start Over</gui>
       button in the bottom right. It will start a new game of the default
+      <!-- No need to say "bottom right", the users are not blind! they can see for themselves-->
       puzzle, <gui>Only 18 steps</gui>.</p></item>
+
+      <!--This needs to go as a new section, on how to play different puzzles other than default one -->
       <item><p>To play a different puzzle, click the <gui style="button">View
       Puzzles</gui> button, choose a game category and start a new puzzle by
       double clicking on it.</p></item>
     </steps>
  
+ <!-- Dont need this section -->
   <section id="new-game-on-close">
   <title>Start a new game on completion of a puzzle</title>