Ellis Pratt, Director of Cherryleaf joins us in this episode of Knowledgebase Ninja and shares what it takes to be a great technical writer and how to create quality documentation. Check out all the other episodes of Knowledgebase Ninjas.

Connect with Ellis Pratt and Cherryleaf’s Knowledgebase here:

• Ellis Pratt
• Cherryleaf’s Knowledgebase

Key Takeaways:

Ellis’s journey into technical writing and documentation…

After getting a business degree, Ellis worked in accounting and then transitioned into providing technical support for a software company. His real interest was in sales and management, which led him in finding a spot at TMS (technical writing services company). After a period of time at TMS he then moved to Digitext which was another company in a similar field. When the internet became a thing, Ellis was also involved in setting up intranets for central governments and organizing content around that.

In 2002, he co-founded Cherryleaf, which provides technical writing services for a variety of companies. They also train technical writers and occasionally help in the writer recruitment process for companies.

Ellis’s most important factors for generating great documentation

Ellis says the most important factor in documentation is figuring out what the client is looking for. A good idea is to ask lots of questions such as:  

• Why do they need documentation? 
• What time frame are they thinking of?  
• What uses do they want from this piece of documentation? 

This helps to clarify the reason for creating the documentation and what the end result should be. Once these factors are gauged, it becomes easier to create the content which will be in line with the clients’ requirements. 

Essential qualities for a technical writer

According to Ellis, the most important quality for a technical writer is the ability to write in a clear, concise, and crisp manner. However, for a complete, well-rounded writer of excellent skill, he lists out the following qualities:

• Writing clearly and to the point
• Empathy for the end-user and their experience
• The ability to manage tasks on time
• Knowledge about the field, they are writing for. While this is not as important as the other factors, it gives a writer an edge over others
• Expertise and knowledge of the tools available. Again, Ellis thinks this is not as important as the others, but it certainly helps a writer towards excellence

Key elements for measuring the quality of your documentation

Documentation quality can vary, depending on the needs of a client, but as a general rule at Cherryleaf, before submitting work to a client, Ellis tends to check it for some quality measures. These measures have been developed and published by IBM in a book as well as numerous articles. These quality measures are:

• Accurate content with no mistakes
• Examples that can help users to understand and relate to the content that is new or difficult, by relating it to previous knowledge
• The ease with which a user can find what they are looking for
• Focus on helping the user complete a task or recognize an error
• Simple to understand
• Complete with no missing parts 
• The coherent organization, with everything arranged in a logical manner
• Style appropriate to the content in understandable and simple English
• Visually attractive, using visual aids like diagrams, and flowcharts, where needed

The goal of good documentation

Good documentation for websites ensures that end-users or customers have a smooth experience using the website, and also increases attention as well as customer interaction. This is the goal for most websites.

Unfortunately, Ellis feels that It isn’t easy to measure the effectiveness of documentation, as clients don’t always follow up with the company that actually create the documents, but he does provide a list of some sites that he thinks have made good use of documentation to have a simple and streamlined process and also increase user interaction, naming Stripe.com and the websites for DHL and Monzo Bank.

Who has Ellis learned most from?

• Rahel Anne Bailie – Director of Content at Babylon Health 
• Matthew Ellison – Consultant in Software User Assistance
• Kristina Halvorsen – Founder and CEO at Brain Traffic

Ellis’s top documentation related resources

Ellis recommends attending conferences as well as listening to a variety of bloggers and podcasts:

• Knowledgebase Ninjas
• Cherryleaf Podcast
• Every Page Is Page One
• I’d Rather Be Writing
• Write The Docs
• Scriptorium
• The UX Podcast
• The Not-Boring Tech Writer
• The Manuscript

One piece of advice Ellis would give to his 20-year-old self

In his time at TMS, Ellis learned information mapping, which is a research-based method to write clear and user-friendly information. He believes it gives a great foundation to learn to write clearly and organize information in a well-structured way and is suited to the field of documentation and technical writing.

Subscribe To Knowledgebase Ninjas:

• Apple
• Spotify
• RSS

Quote: