Category Archives: Technical Writing

I Wonder That You Will Still Be Writing; Nobody Reads You

Agile got (at least) one thing right: stop writing documents no one’s ever going to read. If you want to honestly assess what will or won’t be read – and therefore what should or shouldn’t be written – you should … Continue reading

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

Don’t Let HR Block Your Next Technical Writer

First let me clarify – I’ve nothing against HR and their involvement in the hiring process. What I object to very specifically are two habits: letting HR choose who gets interviewed, and letting HR do the first interview and veto … Continue reading

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

Do not Hire This Person: Technical Writers Edition

Three things some technical writers say that should serve as a warning sign that you may not want to hire them: “I only need to understand it at the UI level”. If you don’t understand how and why things happen, … Continue reading

Posted in Technical Writing | Tagged | Leave a comment

QA: Need Help Finding UX Faults? Ask the Technical Writers

Technical writers have a very clear goal: explain the interface. That means they notice, instantly, when it’s inexplicable. If your interface is a confusing mess with overly-complicated procedures, buttons that make no sense, important options hidden in sub-menus and related … Continue reading

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

Make Yourself a Better Writer: Treat Every Document Like a Writing Sample

The only way to improve, the internet keeps telling us, is to push yourself past your comfort zone so that you’re always learning new things. Writing day in and day out, however, can mean you start to churn¬†out documents on … Continue reading

Posted in Articles, Technical Writing | 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

Five Types of Questions to Avoid in Technical Writing Interviews

I’ve written about good questions to ask technical writing candidates. There are, of course, many more good questions you could ask. There are also many bad questions you shouldn’t bother with. Here are five types of questions you should avoid.

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

Lessons I Learned as a Tester, 4: Testers Should Write the First Draft and Approve the Last Draft of Release Notes

You might say I learned this lesson as a technical writer, too.

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

Five Questions for Technical Writing Interviews

These questions are for experienced candidates, not aspiring writers, and are meant to reveal general attitudes and methods. You want to see how people think, and how they act and react to other writers.

Posted in Articles, Technical Writing | Tagged | 1 Comment