Home → Feedback →

Style of User Guide

• Edit

Martin S Taylor

30 Jan, 2015 11:33 AM

Without wanting to sound overly stuffy I'm a bit concerned at the style of the First Steps User Guide. GPG is a very serious piece of programming, and you ought to be projecting a serious, businesslike image.

There's nothing wrong with keeping instructions light (light often equates to clear) but I'd be reluctant to trust software which is introduced with "Why hello there beautiful!" and uses flippant instructions such as "We're very sorry, but you'll have to answer a very complicated question now and based on that, you'll take different steps through this tutorial. Scaaary!"

1. Support Staff 1 Posted by Steve on 05 Feb, 2015 06:24 PM

   

   Hi Martin,

   good point. We agree and have cleaned that KB article. Let me know what you think of the new version: http://support.gpgtools.org/kb/how-to/first-steps-where-do-i-start-...

   Kindly,
   steve

   • Edit

2. 2 Posted by Martin S Taylor on 20 Feb, 2015 12:11 PM

   

   Hi Steve:

   Wow! I'm impressed. I didn't expect you to take action so promptly, though I'm very pleased you did.

   The new version is so much better, and stands well on its own. However, if you'll permit me (as a former professional technical writer) to suggest a few extra amendments:

   1. In the paragraph "Create a new key", you write

   It will let you create new keys, edit existing ones, search for your friends keys, and much much more.

   The style of this doesn't fit with an instructional guide. It's a paragraph teaching beginners how to create a new key, and they don't need to be told how much more GPG keychain is used for. Certainly the "... and much, much more." is a bit of a hangover from the previous gushing style.

   2. The sentence in the sub-paragraph "Email Address" has the sentence

   You should use the email address, from which you send mails from in Mail.app.

   which is a bit awkward. How about

   Enter the email address you normally use when sending mail.

   3. You'll lose the option to revoke your key and open encrypted message or files among other things.

   Since this is a beginners' document, I wouldn't start by talking about revoking keys. Just put

   If you do, you won't be able to read encrypted messages or files.

   4. "Yeah, you are now ready to encrypt your message."

   I think the "Yeah" is a bit out of place.

   5. "This indicator will show you that your mail is gonna be signed and/or encrypted."

   Make it "This will show you that your mail will be signed and/or encrypted."

   6. "Use GPGTools - 'cause it's worth protecting what you love. :)"

   Again, in my opinion this is a bit too chatty for serious software. The slogan is fine, but I'd write 'because' rather than 'cause, and I woudn't put the smiley at the end.

   Hope all this is useful, and doesn't come across as a miserable old guy enforcing what they taught him at school because it's 'the right way to do it'. Feel free to ignore the advice, of course.

   And thanks for the great software.

   Martin S Taylor

   • Edit

3. Support Staff 3 Posted by Steve on 25 Feb, 2015 04:20 PM

   

   Hey Martin,

   constructive feedback is always welcome. We don't take this as grumpy advise at all. I am annoyed by badly written tutorials myself.

   1. It will let you create new keys, edit existing ones, search for your friends keys, and much much more.
      →
      It will let you create new keys, edit existing ones and search for your friends keys.

   2. You should use the email address, from which you send mails from in Mail.app.
      →
      Enter the email address you normally use when sending mail.

   3. You'll lose the option to revoke your key and open encrypted message or files among other things.
      → (paragraph streamlined a little)
      You should never delete your secret key. If you do, you won't be able to read encrypted messages or files. There's more trouble to it, but let's keep it at that for this quick and dirty tutorial.

   4. Yeah, you are now ready to encrypt your message.
      →
      You are now ready to encrypt your message.

   5. This indicator will show you that your mail is gonna be signed and/or encrypted.
      →
      This will show you that your mail will be signed and/or encrypted.

   6. GPGTools - 'cause it's worth protecting what you love. :)
      →
      GPGTools - 'cause it's worth protecting what you love.

   Merged. Thanks a bunch for your improvement suggestions.

   Kindly,
   steve

   • Edit

4. Steve closed this discussion on 02 Jun, 2015 12:13 PM.