If someone’s having to read your docs, it’s not “simple”

As a developer, I often find myself knee-deep in a new technology – perhaps investigating a library, or learning a language. I’m trying to frame new concepts in my head, applying my own data and architecture on the fly to the generic explanations in the docs. It’s hard! Which is why it’s jolting to read something like:

  • [This library] makes it painless to [do difficult thing].
  • [Complicated thing] made simple and easy.
  • All you have to do is just [difficult thing].

If someone’s been driven to Google something you’ve written, they’re stuck. Being stuck is, to one degree or another, upsetting and annoying. So try not to make them feel worse by telling them how straightforward they should be finding it. It gets in the way of them learning what you want them to learn.

You’re keen to share your excitement!

When I’m writing technical docs, annoyingly, I find myself putting “just” in all the time, despite having strongly-held views about words such as this. I think it’s because I’m so keen to share my enlightenment. It’s exciting that the code I’ve written might be able to help, and naturally I’m keen to communicate that. A bit of light editing lets you keep the enthusiasm for the code, lose the bits that could be interpreted as condescending, and improve the clarity, to boot.

What’s to be done?

Scan your technical writing for words such as easy, painless, straightforward, trivial, simple and just. Chances are your writing will be clearer as a result of removing them. Here’s a cleaned-up real life example, showing that the joy of the code can be better explained without all the “just”s and “simply”s.

Original:

2.1.4 Calling the Mailer

Mailers are really just another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they are just sending it out through the email protocols instead. Due to this, it makes sense to just have your controller tell the Mailer to send an email when a user is successfully created.

Setting this up is painfully simple.

First, let’s create a simple User scaffold:

$ bin/rails generate scaffold user name email login
$ bin/rails db:migrate

Now that we have a user model to play with, we will just edit the app/controllers/users_controller.rb make it instruct the UserMailer to deliver an email to the newly created user by editing the create action and inserting a call to 

UserMailer.with(user: @user).welcome_email
right after the user is successfully saved.

Edited:

2.1.4 Calling the Mailer

Mailers are another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they send it out through email protocols instead. A common use of mailers is to send an email when a user is successfully created.

To set this up, first create a User, using the Rails scaffold: 

$ bin/rails generate scaffold user name email login
$ bin/rails db:migrate

Now that there is a user model, edit app/controllers/users_controller.rb to instruct the UserMailer to deliver an email to the newly created user. Edit the create action, adding a call to 

UserMailer.with(user: @user).welcome_email
right after the user is successfully saved.

That’s better: cleaner, less cluttered and less, frankly, infuriating. No programming is “painfully simple”, so let’s make sure our docs don’t put people off using the code we’ve worked so hard to create. Thanks!