How do you assess an example of technical writing?
It can be difficult if somebody gives you a sample, and you’re looking at it for just a couple of minutes. Your eyes are naturally attracted to what you might call the the shiny stuff, the visual impact. It may be harder to assess actually the quality of the writing, the information design, the flow of the information, that is the way in which has been written.
We recommend is you use the same criteria that you would use if somebody was doing work within a
team and you were giving it a quality check before it got published. One of the most common standards or criteria that people use within technical communication is to use a quality criteria that was developed at IBM.
The IBM quality criteria looks at a number of different factors:
- Freedom from mistake or error; adherence to fact or truth.
- Are there any mistakes in the steps that have been described?
- Can people understand it the first time they read it?
- The inclusion of all necessary parts, and only those parts.
- Is there the right amount of detail?
- The inclusion of appropriate examples, scenarios, similes, analogies, specific language, and graphics.
- Is there appropriate use of examples, for explaining terms that might not be familiar to somebody?
- A coherent arrangement of parts that makes sense to the user.
- Is it arranged in an order that makes sense for users?
Retrievability or find-ability
- Users can find specific items quickly and easily.
- Can somebody quickly find the information they’re looking for?
- Correctness and appropriateness of writing conventions and of words and phrases.
- This can relate to plain English or clear English.
- A focus on helping users do tasks that are associated with a product or tool in relation to their jobs.
- Is it focused on the audience’s goal – what they want to achieve?
- Attractiveness and enhanced meaning of information through the use of layout, illustrations, colour, typography, icons, and other graphical devices.
Examples of different types of documents
API documentation example
elearning module example
See the online training samples on our elearning site.
Online Help file example
Available on request.
Policy and procedures examples
- ABC Co Employing new staff policy (pdf)
- Management processes (online)
- Staff handbook example – responsive web layout
Pre- and Post- Brexit procedures examples
Below are two proof of concept examples of a policy document. In these examples, the selling old mobile phones topic contains a filter for pre- and post- Brexit information. Users can use the filter option to switch between both versions.
The benefit of doing this is because the reader doesn’t get overwhelmed with information, and the writer can manage the both sets of information in a single topic.
- Mobile phone policy – version 1 (online)
This example has tabs on the left hand navigation panel.
The funnel icon () tab enables you to exclude content. In this example, you can exclude pre- and post- Brexit information on the selling old mobile phones topic.
The A-Z folder icon () tab enables departments, budget holders and line managers to see which topics are relevant to them.
- Mobile phone policy – version 2 (online)
In this example, you can exclude pre- and post- Brexit information on the selling old mobile phones topic by using the drop down menu at the top of the topic.
It also contains a job role tab that enables departments, budget holders and line managers to see which topics are relevant to them.
Click on the menu icon () to display the navigation window.
Writing reports and proposals
An example of how you could use the AsciiDoc lightweight markup language to write reports and proposals more efficiently. This video is part of our Advanced Technical Communication training course bundle.
Available on request.
Graphic novel examples
- The Content Twins
- Content strategy
- The DITA Man
- This free illustrated 18 page guide, in graphic novel format, explains the business benefits of the DITA authoring standard.
- The CEO and the technical communicator
- This free illustrated 15 page guide, in graphic novel format, explains the business benefits of technical communicators.
There's a lot of stuff we can't show you
- We are nearly always under a non-disclosure agreement with our clients.
- The information is sometimes integrated with the software. This means you’d need to buy and install the application if you wanted to see the content. In other cases, the content may be on the web, but behind a firewall.
- We also give our clients the capability to make changes over time themselves. This means the content on websites might not be what we created originally.
You might gain a better understanding of our capabilities by looking at the case studies from documentation projects.