Category Archives: Technical Writing

Writing for How-To Videos, Part 1: Basic Considerations for Scripts

Two notes before we begin: first, this article is about software how-to videos, not instructional videos that explain a subject or your business plan. Second, this is the first article of two. I’ll present some basic considerations in this one, … Continue reading

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

Questions to Ask Yourself Before Writing an FAQ

Some technical writers hate FAQs. I rather enjoy them, because they’re the only bit of technical writing most people will ever bother reading. But they’re not always an easy thing to write; since FAQs are never full explanations of the … Continue reading

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

Screen-Cap Tips for Beginners

If you’re starting out in technical writing, here are some things to consider when adding screen-caps to user manuals and training guides.

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

Communicating an Existing Interface to a New Designer

When a new designer joins an existing project, the temptation to show the designer the interface rather than the spec is hard to resist, especially if the two are not very similar. The problem is that some information that was … Continue reading

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

Talking to Users: Polite, Friendly and Helpful UI (Part 1)

Because I am both a technical writer and a software tester, one of my pet peeves is an interface that falls apart when it needs to communicate anything to the user. On every project I see code instead of text, … Continue reading

Posted in Articles, QA, Technical Writing | Tagged , | 2 Comments

How to Get From Zero to User Manual

One of the challenges of project work is that you have to get into things quickly and without much help – in many places, people will have neither the time nor the inclination to teach you. Remember that if you … Continue reading

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

TMI: The Expert Fallacy

The natural assumption of most software companies is that an application intended for experts in the field doesn’t need to explain anything beyond the interface. The user is supposed to know the work-flow and terms at least as well as … Continue reading

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

How to Make Your Texts Easier to Scan

Scanning is the quickest way to get through reading material: glance at it just long enough to find the bit you’re interested in. It’s a big time-saver for readers and they’ll thank you for making your text as easy to … Continue reading

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