Posted on

Mistakes to Avoid when Evaluating Technical Content

How do you evaluate the quality of your documents in a way that’s impartial, accurate, and easy to implement?

Recently we looked at how to create scoring frameworks (usually in Excel) to evaluate and score technical documents.


From one angle, the scoring is the easy part. What’s more difficult is getting people onside.

Encouraging them to use the framework, score correctly, and most important not see it as a tool which will be used to show up their weaknesses.

That’s the usual reaction.

Mistakes to Avoid when Evaluating Technical Content

If I score low, will my position be threatened or my performance reviews be affected?Content

This is a valid question as ultimately writers will be assessed partly on how they score. However, it should only be one factor in their overall assessment. With that in mind, let’s look at how to implement a scoring system that gets accepted, improves quality, and can be scaled.

  • Give fair warning. No one likes to be caught unawares. So, let the writers know in advance that this is on the agenda and you and the team will be working on it in the coming weeks or months. This allows people to see what’s coming and prepare questions in advance.
  • State your intentions. Once the project starts, explain why you’re doing this. Is it because you’ve been told to (not my idea but…) or because you feel the team will learn and benefit from it. Explain why. Give examples.
  • Define the scope. Is everything going to be assessed? Probably not. Identify the scope of the project, ie what content will be evaluated first, for example, user guides, release notes, online or help, and use this as a baseline.
  • Start small. The first phase is really to get the wheels in motion and find where it can be improve. Don’t expect too much from the numbers. It’s also the phase where you try to get the scoring system embedded into day to day operations, so later it’s just another task to be completed.
  • Describe how it works. Walk the team through the process. Show them how scores are awarded, how (and why) weights are applied, and how this will be tracked over time. Why? It reduces fear of the unknowns and neutralizes some of the gossip and Chinese whispers.
  • Don’t work in isolation. Instead of developing this by yourself – and then trying to launch it by yourself – get others involved early. Look for writers who are keen to better themselves, want to learn more, and are interested in expanded their skillsets. These will usually have the drive, energy, and attitude to help you get the system up and running.
  • Dealing with naysayers. Expect resistance. There will always be team members who’ll try to undermine your position, find flaws in your plan (answer: so, how would you suggest we improve it?) and encourage others to do likewise. While this is to be expected, at least to some degree, you may need to talk to team members whose attitude is influencing the team negatively.
  • Explain consequences. Be honest. Scores reflect your performance at work. However, they should only reflect part of your overall performance. For that reason, clarify how this will affect writers, for example, as bonuses are often determined by performance reviews, and what may occur if writers are consistently getting low scores.


Your team is more likely to accept and use the new scoring system if they’re involved from the get go. Let them know why you feel this will help their careers and if they have suggestions on ways to judge the quality of the content.

Delegate tasks so everyone is involved to some degree, for example, creating templates in Excel, adding best practices to the wiki, and updating style guides if necessary.

Posted on 8 Comments

How To Write Technical Documentation For APIs

One of the threads on LinkedIn is how to write technical documentation for APIs. It’s been many years since I’ve documented an API (Java & Oracle) so if you have any thoughts on the best way to do this, then please jump in.

An application programming interface (API) is an interface implemented by a software program to enable interaction with other software, much in the same way that a user interface facilitates interaction between humans and computers.

What is an API?

APIs are implemented by applications, libraries and operating systems to determine the vocabulary and calling conventions the programmer should employ to use their services. It may include specifications for routines, data structures, object classes and protocols used to communicate between the consumer and implementer of the API. Wikipedia


An API is an abstraction that defines and describes an interface for the interaction with a set of functions used by components of a software system. The software that provides the functions described by an API is said to be an implementation of the API.

An API can be:

  1. Generic — the full set of API that are bundled in the libraries of a programming language (e.g. the standard Template Library in C++ or the Java API)
  2. Specific — meant to address a specific problem, like the Google MAPs API or the Java API for XML Web Services.
  3. Language-dependent — available only in a given programming language. It is only available by using the syntax and elements of that language to make the API convenient to use in this context.
  4. Language-independent — written in a way that means it can be called from several programming languages. This is a desired feature for a service-oriented API that is not bound to a specific process or system and may be provided as remote procedure calls or web services.

For example, a website that allows users to review local restaurants is able to layer their reviews over maps taken from Google Maps, because Google Maps has an API that allows it. Google Maps’ API controls what information a third-party site can grab, and what can be done with it.

“API” may be used to refer to a complete interface, a single function, or even a set of multiple APIs provided by an organization. Thus, the scope of meaning is usually determined by the person or document that communicates the information.

API Guidelines

Here are some sites that offer guidelines and examples of API documentation.

Twitter’s API Documentation

Twitter has done a great job documenting its API and breaks out all the different component.

“The Twitter API consists of three parts: two REST APIs and a Streaming API. The two distinct REST APIs are entirely due to history. Summize, Inc. was originally an independent company that provided search capability for Twitter data. The Streaming API is distinct from the two REST APIs as Streaming supports long-lived connections on a different architecture.”

Tips for writing API documentation

What advice would you give to someone writing their first API document set? What mistakes do technical writers make when approaching this area?

FYI: Twitter API: Up and Running: Learn How to Build Applications with the Twitter API

Posted on

How to Write a Target Audience Questionnaire

Creating a training plan? Before you do this, you need to step a step back and work out what your colleagues need to learn. Continue reading How to Write a Target Audience Questionnaire

Posted on 4 Comments

Favorite 10 Technical Writing Tools

drinking sheepI’ve used the same technical writing tools for the last 5 years. A few products have come across my desk but nothing that really blown me away.

Here’s a run-down of what I use to write my technical documents. No order of preference. Which should I keep? Which should I replace?

Continue reading Favorite 10 Technical Writing Tools

Posted on

How to Write a Capacity Plan

capacity-plan-buildingDeveloping a Capacity Plan is vital if you want to understand how much capacity will be required to support your IT systems and, by extension, the infrastructure that supports it.

Think about it.

If you plan to install a new large-scale solution, for example, IBM WebSphere or SAP, you also need to consider the impact these will have on your existing systems.

How to Write a Capacity Plan

1. Capacity Planning & Outsourcing

Another area where Capacity Plan is vital is outsourcing. Say you plan to outsource your Help Desk to a third party firm.

Well, for them to support the system technically (not from a business perspective) they need to prepare a Capacity Plan that details the technical requirements to support this solution.

2. Developing a Capacity Plan strategy

  • Assess the current solution and component performance
  • Identify constraints that may be imposed on the system
  • Use this information to develop the Capacity Plan for component acquisition, configuration, and upgrade.
  • Make recommendations on how the Capacity Plan should be maintained, monitored and updated as necessary.

3. Benefits of a Capacity Plan

Developing a Capacity Plan ensures that business and technical requirements can be supported by the infrastructure and application elements of the new solution. In this case, the Help Desk or the IBM back office solution.

4. Management Guidance

The Capacity Plan provides management with:

  • Breakdown of the resource capabilities required to operate the solution
  • Assessment of current capacities
  • Estimates on the resources and services to be upgraded and acquired
  • Projection of resource and services capacities that may be required by the solution
  • Capacity Planning ensures that there is sufficient processing capacity to run these new applications and for some predetermined time into the future as your business expands.

A well-defined Capacity Plan takes into consideration the likelihood that your business will grow and provides the appropriate estimates so you can develop the systems in line with these projection and also budget accordingly.

5. Capacity Plan Risks

If your company runs out of system processing capacity at some point (for example, due to increased user numbers, higher business volumes), the system’s performance will begin to suffer and you may be faced to upgrade the system (and associated applications) or move to a different more powerful system/server to process these applications.

To ensure that these applications can process the application load at cutover, and for some period of time following this, develop and check your capacity plan.

Capacity Plan Template

The method and results of this study should then be captured in the Capacity Plan document.