Here’s some examples, and some help on how to assess them
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 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.
One of the most common standards or criteria that people use within technical communication is to use a quality criteria developed originally by IBM.
The IBM document quality criteria
- Freedom from mistake or error; adherence to fact or truth.
- Are there any mistakes in the steps that have been described?
- 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?
Retrievability or find-ability
- Users can find specific items quickly and easily.
- Can somebody quickly find the information they’re looking for?
- 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?
- 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?
- A coherent arrangement of parts that makes sense to the user.
- Is it arranged in an order that makes sense for users?
- Correctness and appropriateness of writing conventions and of words and phrases.
- This can relate to plain English or clear English.
- Attractiveness and enhanced meaning of information through the use of layout, illustrations, colour, typography, icons, and other graphical devices.
API documentation examples
This is a developer portal for embedded systems:
We also have a dummy REST API documentation portal we can show on request.
Onboarding video examples
Software onboarding video example
Writing reports and proposals demo
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.
elearning module examples
The Mathspeak project
Cherryleaf is part of the Mathspeak project, a partnership between European educational practitioners and the creators of educational materials. Funded by the European Commission’s Erasmus+ project, Mathspeak aims to provide non-native language speaking students with the means by which they can do maths better. Contact us to get access to a working draft of the website.
Our elearning site
We have developed a number of online training courses that help people become better business or technical communicators. You can view a number of online training samples from these courses.
Policy and procedures examples
Business process examples
This example has flowcharts with hotspots that take the reader to more detailed information.
- Management processes (online)
Online employee portal example
Here is a proof of concept for publishing HR procedures online. Word documents can be converted into an online employee portal.
Online Help examples
Online Help portal example
Here is a proof of concept for an online Help portal that deflects calls to the support lines.
Knowledge base example
Here is a proof of concept for a knowledge base that deflects calls to the support lines.
Writing Help files is one of the key things that we do. However:
- 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.
This means we prefer to understand a little more about your situation, so that we can show you the most appropriate examples. Contact us, and we can do this.
User guide examples
Writing user guides files is also one of the key things that we do. And again, we prefer to understand a little more about your situation, so that we can show you the most appropriate examples. Contact us, and we can do this.
Comic and graphic novel training guides example
We developed a number of graphic novels to explain the benefits of technical communication and some of the technologies used. This was mostly for fun. It’s not a core part of what we do.
- 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.
You might also be interested in the case studies from documentation projects.