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

You’re knee-deep in a new technology – perhaps investigating a library, or learning a language. You’re trying to frame new concepts in your head, applying your own data and architecture on the fly to the generic instructions 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 Googled to find your writing, 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.

You’re keen to share your excitement!

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

What’s to be done?

Scan your technical writing for words such as “easy”, “painless”, “straightforward”, “simple” and “just”. Chances are your writing will be cleaner 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. Due to this, it makes sense to have your controller tell the Mailer to send an email when a user is successfully created.

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

$ bin/rails generate scaffold user name email login

$ bin/rails db:migrate

Now that we have a user model to play with, we can edit app/controllers/users_controller.rb, and instruct the UserMailer to deliver an email to the newly created user. Edit the create action and insert 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!

–from someone who reads a lot of tech docs, sees these words everywhere, and gets a little sadder each time.

Originally posted at https://justsimply.dev

More things at https://consonance.app/blog