The Software Architect Elevator

Chapter 20. Writing for Busy People

Don’t Expect Everyone to Read Word for Word

If you don’t have time to read, look at the pictures

Most organizations are full of boring documents that remain largely unread. That doesn’t mean that documentation is a bad idea. Done well, it’s still the best vehicle to proverbially get everyone on the same page across a wide audience. Over time, brief but accurate technical position and decision papers have become a trademark of my architecture teams.

While the title of this chapter is a pun on the titles of popular books such as Japanese for Busy People, it intentionally implies an ambiguity that we are both writing for a busy audience and are busy authors as well.

Writing Scales

Sadly, writing takes much more effort than reading, but skimping on writing is penny-wise and pound-foolish because the written word has enormous advantages over the spoken word or slide presentations:

It scales

You can address a large audience without gathering everyone in one room (podcasts, admittedly, can also accomplish that).

It’s fast

People read two to three times faster than they can listen.

It’s searchable

You can find what you want to read quickly.

It can be edited and versioned

Everybody sees the same, versioned content.

So, writing pays off when you have a large (or important) enough audience. The biggest benefit, though, is Richard Guindon’s ...