Tag Archives: Writing for non-writers

Recommended Reading: How to Think About Writing

Oliver Burkeman reviews the basics of thinking about writing.

Posted in Reading | Tagged , | Leave a comment

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 … Continue reading

Posted in Beginner Tips, Technical Writing, User Manuals | Tagged , , , | 1 Comment

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 … Continue reading

Posted in Articles, Technical Writing | Tagged , | Leave a comment

Punctuation in UI: the Oxford Comma

The Oxford comma, or serial comma, is the comma that sometimes appears in a list before the last “and”, “or” and so on. It has somehow become a battleground of punctuation, because some people always use it while others never … Continue reading

Posted in Technical Writing | Tagged , , | Leave a comment

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 … Continue reading

Posted in Articles | Tagged , , | Leave a comment

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 … Continue reading

Posted in Articles, Technical Writing | Tagged | Leave a comment

Working With Known Bugs

There are two types of known bugs in the world. The “official” known bugs – those that are known to the Head of QA and the Head of Development – and the “unofficial” known bugs, those that are known to … Continue reading

Posted in Articles, QA | Tagged , , | Leave a comment

How to Improve Your Bug Reports

There are days when your bug reports are the only communication a programmer receives from the outside world (ignoring e-mails, chats, Facebook, Twitter and mobile texting); make them count.

Posted in Articles, QA | Tagged , , | Leave a comment