Beyond Clicking: Refactored User Help for Passwords and Keys

Documentation doesn't just explain what buttons to click or what keys to press. In some cases it provides reference information, or it explains a particular concept that underpins a certain task or series of tasks.

Explaining concepts is particularly important when those concepts are both complicated and important to performing a task. This is the case with concepts related to encryption. If people can understand complicated encryption concepts, they may be more likely to correctly use and maintain their encryption tools, making it more likely that they will keep their communication secure.

Updates to the Passwords and Keys Help

To make encryption concepts a bit more accessible (and thus help people correctly use encryption tools), I've re-factored the user help for the Passwords and Keys application. Passwords and Keys is the application that manages SSH and PGP/GPG keys in GNOME, and the updated help will be available in the GNOME 3.16 release.

The updated help follows the layout of user help in other GNOME applications, making it easier to scan the help and find relevant topics. I've also added a few new topics:

Some highlights include:

• A new, introductory section that groups together fundamental encryption terms and concepts.
• A new topic that explains the difference between Public and Private keys.
• Suggestions for securely backing-up your keys.
• Instructions on how and when to revoke your keys.
• Showing how to sign someone else's PGP/GPG key.

There's more to it, but that is a short list of some of the topics that stand out to me as useful. I think it's good that we'll have that help included on-disk (and also on the web) for anyone who needs it.

Credit Where Credit is Due

As for the content of this help, I give credit to Aruna Sankaranarayanan who wrote much of the user help for Passwords and Keys. I had written some if it, but she wrote a lot of it - it's thorough and well-written. Although I have added a few new topics, most of what I've done is to refactor the layout of the help to make it easier to search and navigate.

We'll likely have a some more updates before the 3.16 release, but if you have any tips or suggestions for how we can improve the help, feel free to be in touch.