C# – What is a derived class?

As the name implies, a derived class originates from another class, which in C# is called a base class. A derived class is a specialization of the base class. A derived class is created from an existing base class. It inherits the member variables and methods of the base class from which it is derived. […]

User Guide Checklist

This checklist summarizes the recommended structure and contents for User Guide documents. Introduction In this section, introduce the User Guide and cover the following areas: – Intended readers – identify the different user types, for example, system operators, home users, and experts. For each, identify the assumed level of experience and highlight the sections of […]

How to Write RESTful APIs

The following example shows how to document an API. This example is taken from the Bing Ads Content API, which is a RESTful API. RESTful API Example – Get Single Item This section describes the type of API and some details about the type of operations it performs. The Bing Ads Content API is a […]

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 […]

How to write a Use Case

This tutorial explains how to write a use case. This is Herman, he’s an Actor is our Use Case tutorial. Read more what he does here. What is a use case? A use case is a sequence of actions that provide a measurable value to an actor. Another way to look at it is a […]

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 […]

10 Ways To Improve Your Documentation Plan Right Now

One of the difficulties when creating documentation plans is determining the correct figures for the amount of work involved. For example, if you’re creating a user guide for an application you know quite well, then it’s easy to estimate the amount of work involved. And if you’re doing the writing, then you can also gauge […]

5 Ways To Differentiate Yourself as a Technical Writer

Feeling ignored? What’s that? No pay respects the hard work you do as a tech writer. Sad, isn’t it? Very sad… Ever wonder why? Ever wonder what you need to do about it? Hmmm? Tom Peters says, “the value of services will continue to fall” and that the only way to survive is to differentiate […]

Who Makes More Money? Technical Writers with Language or IT Skills?

Kai raised an interesting point about which skill (writing/technical) takes longer to master. Knowing how to structure and present information to users? Or knowing how to use a product or application? That got me thinking. If you want to make money as a technical writer, which area should you focus on? Sharpen your writing skills or deepen your technical knowledge, for example, learning how to document an API?

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 I Set Priorities: Get Things Done

Ross Kimbarovsky asks: “How do you decide what to do next? Should you write a blog post? Answer emails in your inbox? Make several sales calls? Spend time on Twitter? Or should you call a team meeting to discuss a customer problem? Ross adds that successful people are successful in part “because they are good […]

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 […]

Robohelp: Why Short Topic Names Improve Navigation

The length of the topic title, i.e. the number of characters, needs to be considered when creating topics for online help. Let’s say you’re creating different topics in RoboHelp. Procedures, reference, and conceptual materials. Each of these needs an intuitive and meaningful name. That makes sense. However, you also need to consider the length of the topic […]

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? […]