Quick Writing Tip: Don’t Add Images Until the Text is Done

Here’s a quick writing tip for user manuals: don’t add your images to the manual until you’re done writing your text. This has two advantages. The first is that when you add images one at a time over the long course of writing a manual, it’s easy to overdo it. When you add them all …

Stump Documents: on Failures to Write Transferable Information

There is a general problem in software, more pronounced in minimalist Agile efforts, of documents that look good at the time of writing, but do a poor job of transferring information. I call these “stump” documents because readers are stumped when they try to learn from them.

Capital!

Capitalization seems to be a weak point for many in software. Perhaps because code (and odd company names) teach us that words can have a capital letter in the middle, capitalization of UI text is often more creative than is strictly necessary. Capital letters aren’t important only because some of your users are grammar geeks; …

Don’t Dumb it Down; Layer it Up – Writing Tips for Engineers

When explaining complicated ideas, your goal shouldn’t be to dumb things down – you’re here to teach, not to help people avoid learning. But the best way to teach is not to start at the expert level and hope your readers follow along – it’s to start at the bottom and layer it up. Give …