[seahorse/wip/userdocs: 128/363] help: Comment on some of the 'learning' pages

[Ekaterina Gerasimova <egerasimov src gnome org>]

commit 49fc91c5548924b1a67f2a6e49d1d69bad3cd9fb
Author: Stef Walter <stefw gnome org>
Date:   Tue Feb 26 11:44:14 2013 +0100

    help: Comment on some of the 'learning' pages
    
    Hopefully this commit will be squashed when me merge this branch.
    But we can worry about that later.

 help/C/encryption-dsa.page          |    8 ++++++++
 help/C/encryption-rsa.page          |    7 +++++++
 help/C/key-create-vs-setup.page     |    5 +++++
 help/C/key-fingerprint.page         |   15 +++++++++++++++
 help/C/key-strength-define.page     |   11 +++++++++++
 help/C/what-is-certificate-key.page |    5 ++++-
 help/C/what-is-keyring.page         |   11 +++++++++++
 help/C/what-is-ssh-key.page         |    3 +++
 8 files changed, 64 insertions(+), 1 deletions(-)
---
diff --git a/help/C/encryption-dsa.page b/help/C/encryption-dsa.page
index 3b611fa..641190c 100644
--- a/help/C/encryption-dsa.page
+++ b/help/C/encryption-dsa.page
@@ -21,4 +21,12 @@
     <item><p>Third step...</p></item>
   </steps>
 
+  <!-- stefw: it would be difficult to recommend RSA vs. DSA to users
+     and help them understand why they would choose one over the other.
+
+     Unless you already have a plan for what will go here, it seems
+     this is a hard topic, but could include some information from
+     wikipedia for interest purposes only.
+  -->
+
 </page>
diff --git a/help/C/encryption-rsa.page b/help/C/encryption-rsa.page
index d264e66..dad6b15 100644
--- a/help/C/encryption-rsa.page
+++ b/help/C/encryption-rsa.page
@@ -15,5 +15,12 @@
 
   <title>What is RSA encryption?</title>
 
+  <!-- stefw: it would be difficult to recommend RSA vs. DSA to users
+     and help them understand why they would choose one over the other.
+
+     Unless you already have a plan for what will go here, it seems
+     this is a hard topic, but could include some information from
+     wikipedia for interest purposes only.
+  -->
 
 </page>
diff --git a/help/C/key-create-vs-setup.page b/help/C/key-create-vs-setup.page
index 68a9f2d..d7b9f41 100644
--- a/help/C/key-create-vs-setup.page
+++ b/help/C/key-create-vs-setup.page
@@ -23,4 +23,9 @@
     <item><p>Third step...</p></item>
   </steps>
 
+  <!-- stefw: I'm assuming this is assuming to the buttons availalbe when creating
+     an SSH key. Is there a better way to represent this option in the UI?
+     In any case the page on this topic should be specific to SSH keys and not
+     a general title.
+  --> 
 </page>
diff --git a/help/C/key-fingerprint.page b/help/C/key-fingerprint.page
index 4606414..c391a8c 100644
--- a/help/C/key-fingerprint.page
+++ b/help/C/key-fingerprint.page
@@ -23,4 +23,19 @@
     <item><p>Third step...</p></item>
   </steps>
 
+  <!-- stefw: Suggest documenting that the key fingerprint is the
+  only way to uniquely tell the difference between two keys.
+
+  Two keys may have the same name and description. The label or name
+  is no guarantee that the key represents the person described in the label.
+
+  The way to guarantee that you have a given key is to compare the
+  fingerprint with the person who owns the key.
+
+  For SSH keys this is done when you initially connect to a server.
+
+  For PGP keys this is usually done through the web of trust. Where someone
+  you know signs a key, and vouches that the key with a given fingerprint
+  is owned by the person noted on the label.
+  -->
 </page>
diff --git a/help/C/key-strength-define.page b/help/C/key-strength-define.page
index d3fb095..db9a291 100644
--- a/help/C/key-strength-define.page
+++ b/help/C/key-strength-define.page
@@ -22,6 +22,17 @@
     the reader will be able to....</p>
   </comment>
 
+  <!-- stefw: I would suggest basing this page off the current
+    reccomendations for key strength. The basic concepts for key
+    strength, is that dependeng how long (in time, years) you want something to remain
+    secure, you choose a given key length.
+    
+    This page might be a source for our recommendations in the help file:
+    http://www.keylength.com/en/3/
+    
+    Note that in general in seahorse we ar etalking about the Assymetric key strength
+    not the Symmetric ones.
+  -->
   <p>Short introductory text...</p>
 
   <steps>
diff --git a/help/C/what-is-certificate-key.page b/help/C/what-is-certificate-key.page
index ce1a6d9..8759137 100644
--- a/help/C/what-is-certificate-key.page
+++ b/help/C/what-is-certificate-key.page
@@ -17,5 +17,8 @@
   will see many <em>Certificates</em> listed alongside your PGP and SSH keys.
   . . . </p>
   
-
+  <!-- stefw: Suggest noting that certificates are received from an 
+    Enterprise or Certificate Authority to be used for accessing
+    web services, email, and other things like that.
+  -->
 </page>
diff --git a/help/C/what-is-keyring.page b/help/C/what-is-keyring.page
index efa1941..ea18c4e 100644
--- a/help/C/what-is-keyring.page
+++ b/help/C/what-is-keyring.page
@@ -29,4 +29,15 @@
     <item><p>Third step...</p></item>
   </steps>
 
+  <!-- stefw: is this page really necessary, at least with this title?
+    Ideally we would remove the terms 'GNOME keyring' from the user
+    interface of seahorse. As far as the user is concerned his/her passwords
+    are stored by the password manager: seahorse.
+
+    There are some concepts to describe about creating additional keyrings
+    for different passwords, and how some keyrings can be unlocked automatically
+    whereas the user may want to keep others locked, and only unlock them
+    when they want to look inside.
+  -->
+    
 </page>
diff --git a/help/C/what-is-ssh-key.page b/help/C/what-is-ssh-key.page
index 2801080..baf25ed 100644
--- a/help/C/what-is-ssh-key.page
+++ b/help/C/what-is-ssh-key.page
@@ -29,6 +29,7 @@
     to unlock messages encrypted with a corresponding public key.</p></item>
   </list>
   
+  <!-- stefw: Suggest linking here to the page what-diff-private-public.page -->
   <p>The advantage of using an <em>SSH key</em> to create a connection between 
   computers is that only the <em>Public key</em> needs to be sent over 
   the network. Transmissions encrypted with a <em>Public key</em> can only be 
@@ -36,7 +37,9 @@
   password. Because only the public key is sent over the network, the key's 
   password is kept secret.</p>  
 
+  
   <p><em>SSH keys</em> are most often used in situations where data security is 
+  <!-- stefw: Suggest removing the word 'very' on next line, as SSH is used routinely these days -->
   very important. For example, a system administrator would use an <em>SSH key
   </em> when connecting to a remote server to perform system updates. A 
   software developer would use an <em>SSH key</em> to submit updated software