Category Archives: Articles

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

Understanding Last Week’s Notes

All testers know the feeling: coming in on a Monday, looking at your notes from last week, and understanding nothing. If not for the handwriting, you’d think they were someone else’s notes. How do you write notes that you’ll understand … Continue reading

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

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

(Read part 1 here) A helpful UI is not as rare as a friendly one, because being helpful is more of a technical skill than a personality. Helpful means informative¬†and organized, as well as comfortable to use. I’ll discuss organized … Continue reading

Posted in Articles, QA | Tagged , | 1 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