Writing Good Directions

Last fall I wrote about the importance of writing good documentation, and part of writing good documentation includes writing good directions. I have a pet peeve when it comes to poorly written instructions of any kind, but unfortunately I’m still learning to do it well myself.

Writing directions can be thankless: you know you provided good directions when people use them and never complain about them. If you write bad directions everyone who gets stuck complains about your work – and usually not nicely because you left them frustrated.

A greyhound wearing a vest labeled donations
No one ever asks where to put money when Leo wears his donations vest.
Good directions, like good recipes, cover all the steps you need to follow, are easy to read at a glance, and provide extra details to help you stay on track. If I’d written up my Drupal Cake recipe as a large block of text without formatting no one would even recognize it as a recipe let alone be able to follow the steps.

Sign with arrow pointing left label Cake and one pointing right labeled No Cake
You don’t have to ask to know where to get the cake.

Over the last few months at work we’ve been updating our development workflow. It started with a large project to migrate our code repositories to Bitbucket and move all support clients onto new testing infrastructure. With a large number of support clients, we had lots of updates to do, so we shared among all the developers. I did the first few conversions and then wrote up a set of directions for other developers to use. The first few times other people walked through them I got corrections, complaints, and updates, and then after a few edits there was silence.  Every couple of days I noticed another batch of clients got migrated without anyone asking me questions. The directions got to be good because no one struggled with them after the first few corrections. But I didn’t get, or expect, compliments on them, but they achieved their purpose.

Switch for a microwave labeled No fish, no curry.
This is from a hotel, but every office should probably have one on their microwave. I doubt the person who created those labels hears about them much unless someone broke the rule and microwaved fish in their room.

It’s easy to complain about directions, but it’s hard to do them right. There is another set of directions at work that I know are bad: because everyone complained about them and then gave up on the process they explain. I need to try again, but frankly it’s hard to get up the motivation to replace the current silence with either new silence (if I succeed) or complaints (if I fail).

Usually when I’m writing up directions the outcome doesn’t matter much. If your Drupal Cake isn’t the shade of blue you were hoping for, or my colleagues have to ask a couple extra questions while migrating site configuration, the world will not end. But there are people who have to write important directions that can save or cost lives.

Even if your directions aren’t signs that hopefully save lives, it is worth trying to do them right. I’ve already admitted I’m still working on getting this right but here are a few things that help me.

  1. Write down the steps as you do the task. Include pictures or screenshots when they are helpful.
  2. Do the task again following your directions to the letter.
  3. As you edit them (because you will find mistakes) add tips about what happened when you made mistakes during your previous attempt to help people know they are off course and how to recover.
  4. Repeat 2 and 3 until you are sure you have removed the largest errors.
  5. Watch someone else follow your directions and see where they get confused – if the task is complex they will get confused and that’s okay for now. Ideally this person should have a different experience level than you do.
  6. Edit again based on the problems that person ran into.
  7. Repeat 5 and 6 until you run out of colleagues willing to help you or you stop finding major errors.
  8. Release generally, and wait for the complaints.

This of course is an ideal. It’s what I did for the migration instructions, but not what I do most of the time. Rarely do we have the time to really work through a process like that and edit more than once or twice. You can shortcut this process some by limiting the number of edits, but if you don’t edit at all you should expect people to complain to the point of giving up.

One last thing. I’ve often been told the first part of writing good instructions is mastering the process. I disagree with that advice pretty strongly. Most of the time I find that beginners write better instructions since they are paying attention to more details. Once I master a topic I skip steps because they are obvious to me, but not to people who need the instructions. That’s why for step five you want someone of a different experience level, someone more junior to help make sure you didn’t forgot to include the obvious and someone more senior to point out that you made mistakes.

Welcome Piscataway Students. I noticed the start of the annual bump in traffic from the Piscataway LMS and figured I’d say hello. A few years ago one of the teachers started to assign this article, so I see a bump in traffic here when they post the assignment.  Tell them I said thank you, and that I’d be interested in hearing from them about how this article gets used in your classes. I hope this year goes well for all of you.

T-Shirts Revisited

A few weeks ago I wrote about not taking free t-shirts from vendors at DrupalCon (or other tech conferences). Well DrupalCon North America 2017 has come and gone so I thought I’d report back on this year’s t-shirts.

My free shirts from DrupalCon 2017

I ended up with seven new free shirts all from places that also offered them in women’s sizes. In addition to the official conference t-shirt I picked up shirts from Lingotek, Linode, Pantheon, Optasy, Chef.io, and Kanopi Studios. There were a couple companies that appeared to be giving out shirts I didn’t talk to so there may be a couple worthy of complementing that I missed.  The big prize for the year goes to Linode whose job ad was a postcard in the shape of a (men’s) t-shirt and read:

Want a career in the cloud hosting industry? We’ve got a shirt in YOUR size.

Pantheon, as usual, had the most popular t-shirts with their custom printing shirts in a wide variety of sizes. That continues to be an amazing way to get people to watch their demo and collect contact information (although to be fair the demo itself is pretty amazing).

There were also a few companies that tried to convince me that bringing “unisex” shirts was the same as if they had brought women’s sizes.

Unisex shirts are, of course, just men’s shirts with a different label. And there are, of course, women who prefer the fit of that cut to shirts sold as women’s. But suggesting they work for everyone is just finding a new language for cheaping out. Arguably its worse than just forgetting that people come in different shapes since it shows someone thought about women looking for shirts but couldn’t be bothered to realize that most people want clothes that take into account their body shape. Ever met a guy who says he’s prefers how a woman’s cut shirt fits his body?

At least I didn’t hear anyone recommending using them as pajamas.

Cached JSON responses in Drupal 8

This week I was working on a Drupal 8 project that includes a page that uses Drupal as a simple proxy to convert a weak XML API into a simple JSON response. To ensure good performance I wanted to ensure I had cached JSON responses.

When I first built the site I hadn’t yet gotten my head around Drupal 8 caching, and so the JSON responses weren’t cached and therefore the page was slow. After some issues with the site caused me to have to look at this part of the project again I decided it was time to try to do something about this.

Drupal 8’s use of Symfony means we have great tools for simple tasks like providing JSON responses. Originally in the controller all I had to do was provide the JsonResponse class an array of data and it would handle the rest:

That’s all well and good if you don’t want your response to ever be cached, but Drupal provides a CacheableJsonResponse class that links up to the rest of the Drupal 8 caching engine to provide much better performance than a stand Symfony JsonResponse. But it turns out the docs kinda suck for explaining how to use it. After a great deal of digging I found this Question on StackExchange which gave me what I needed.

Edit: You must enable the Internal Dynamic Page Cache module to get CacheableJsonResponse to work correctly. Thank you for the correction.