Category Archives: Technical Writing

Over 50? Would a career in technical writing suit you?

If you have good writing skills, enjoy technology, and like to help others understand how things work, then a career as a technical writer might suit you. 1.0      Technical writer work/life balance Technical writing has been very good to me. It’s allowed me to work in China, London, San Francisco, and Amsterdam. Most of the […]

Do you have a technical writer’s personality?

Considering a career as a technical writer? Want to know what kind of people enjoy technical writing the most? Would it suit your personality? Is being introverted an advantage? Can jovial types make it as tech writers? Yes and Yes. Crag on Helpscribe makes the point that, “Personality can also have a strong influence on […]

How to Write Release Notes: Faster, Stronger, Better

release notes template in ms word

So, you want to write release notes but don’t know where to start? Well pull you a chair and let me give you the lowdown. Download – Release Notes template with sample text. Introduce the release notes with text such as the following: These release notes provide information about the documentation for <your product> <version […]

Proof-reading Checklist for Technical Documents

Is there anything worse than sending out an important document and then, just when it’s gone, finding a typo? Always leave some time to check your documents before you send them out. Here’s a checklist to get you started. Proof-reading Checklist Select the entire document – CTRL+A – then click the Language option at the […]

How to Test Technical Documents

This checklist helps you test User Guides and other technical documents. The first step is to ensure the following is in place. Setup the necessary technical environment. Make sure this reflects the user’s settings or as close to as possible. Print out the procedures. Follow the instructions as per the document. Aim to identify any […]

Functional Specification Checklist

Writing the functional specification occurs after we’ve evaluated the product or technology. If we look at the project planning lifecycle, we can see it’s the second process: Evaluating products. Writing the functional specification. Packaging the master project plan. Creating the master schedule. Reviewing Project Plans. PS – you can download a Functional Specification Checklist template […]

Difference Between Run and Execute in Technical Documents

Technical writing is about getting the small details right. The difference between the almost right word and the right word is the “difference between the lightning-bug and the lightning.” Mark Twain So, when writing a user guide, should you say, Run or Execute? From one angle, it doesn’t seem to matter. Everyone knows what you […]

Stephen King Can Make You A Better (Technical) Writer

Scott says, “If you want to improve as a writer, you not only need to write. You need to read. Writing and reading are two sides of the same coin. You need to do both to achieve your potential.” I head downtown most weekends and buy 2 or 3 books, mostly business, history and some fiction. Every so often I run out of options (we’re in Beijing) and get something I usually wouldn’t buy, for example, Iain M Banks. Reading outside my comfort zone stretches me. I encounter writing styles, opinions, and information that I usually side-step.

How to Run (Structured) Interviews

It’s not the questions you ask that matters, it’s the way you ask them. Technical writers, business analysts, and developers all ask questions. They want answers. And some are better than others. Some ask many times to get the definitive answers. Others think they have the answer but, on closer inspection, have overlooked some vital […]

Using Weight Scoring Models for Technical Documents

Recently, we looked at how to determine the quality of your technical documentation. We suggested an approach where you: Identify the scope Identify quality criteria Review a sample of documents Create a baseline Expand the scope All this makes sense. However, we also need to look at how to define a fair scoring system. Why? […]

Checklist: how to proofread technical documents in 15 minutes

You have fifteen minutes to check your technical document before it’s sent to the client. What do you do? Start at one page one and read every word out loud? Maybe, maybe not 🙂 Here’s one suggested approach to proofread any type of document when you’re under pressure. Checklist: how to proofread technical documents in […]

Adobe FrameMaker: 4 Ways to Find and Replace Conditional Text

When it comes to writing technical documents, the ability to create conditional text is one of the main advantages that Adobe FrameMaker has over MS Word. What is Conditional Text? Let’s say you have one document but you want to tailor some content for different readers. For example, you want to add a new warning […]

Technical Documents: 3 Ways to Improve Quality

Who do you write for? This is a problem for many technical writers, especially if you don’t get to meet or interact with your readers. Essentially, you’re writing in the dark. But, that doesn’t mean you can’t improve the usefulness of the documents. Far from it. Technical Documents: How to be more accurate For example, […]