Why Documentation Matters — And How To Deliver It
It is often easy to not notice when documentation is written well — but glaringly obvious when it is written poorly. This is particularly true in advanced analytics — accessible, coherent documentation is a crucial asset for teams working with complex and technical subject matter.
Moreover, many practitioners may find themselves working to implement analytic solutions across a variety of different industries, from insurance and banking to pharmaceuticals. It is vital for these practitioners to understand and use the lexicon used in these industries in order to communicate effectively with the end-user, when setting up the solution and when the time comes to hand it over for deployment in the field.
This article will examine the guidelines we have found helpful when producing documentation at QuantumBlack and explore how clear, accessible documentation is put together in practice by exploring a recent project.
Guidelines For Producing Accessible Documentation
Before tackling any piece of documentation, the first thing you should always ask is, “Who is this for?” and “What am I trying to solve for them?”.
The QuantumBlack Labs team recently discovered when setting out to write the Kedro documentation that there are two distinct segments within the audience who share a common need, familiar concepts and simple explanations:
- Internal teams, familiar with McKinsey vocabulary who are wrestling with industry-specific terminology and acronyms on their engagements.
- External readers in the open source community may not want to learn a new lexicon at all.
To make everyone’s reading experience easy, the team needed to deploy a simple style that appealed to both groups. We have published a very short and basic style guide for the Kedro project, which you can find on our open-source repo. However, there is no point in making rules that put off potential contributors. We accept contributions of text and make sensitive revisions as needed.
Our goal was to keep Kedro’s documentation accessible. That meant avoiding jargon and colloquialisms, as we should not assume that the end reader is always a native English speaker. We also did not set out to make our text edgy or contemporary; the goal is purely to keep it as clear as possible. We use a straightforward vocabulary (although we don’t slavishly follow the Simplified Technical English specification). We abided by the below basic rules:
- Use short sentences and paragraphs. Google’s technical writing course recommends focusing each sentence on a single idea, converting long sentences into lists and reducing the use of extraneous words.
- Use the active voice. The Writing in the Sciences course on Coursera demonstrates how starting sentences with “I” or “We” followed by the main verb makes the sentence a lot easier to understand.
- Prioritise simple verb tenses (past, present, and future). Grammar Monster explains how the English language has 12 tenses, so sticking to these three can help more clearly convey whether something is a past, present, or future action. They also tell us whether the action is habitual, completed, or ongoing.
- Don’t use present participles or gerunds. They can often just make sentences feel more clunky, less direct and harder to comprehend. Geist has a great page about this.
While some find that a picture tells a thousand words, graphics can present problems to others, particularly those who are sight-impaired. To keep our content accessible, we limit the use of graphics unless they are essential and always describe the graphic in the copy.
We also consider those using screen-readers when we include URLs; we make sure the link text is descriptive so it is clear what we are linking to.
Accessible Documentation In Practice
So how is accessible documentation put together in practice? Again we return to Kedro to highlight a recent example.
While some of the original Kedro team have moved on to new projects, the same enthusiasm for documentation and attention to detail endure in the remaining team. Everyone takes great care in writing and editing the product’s documentation with a significant consideration for the needs of the end user. In 2020, Kedro’s documentation won a merit award from the Institute of Scientific and Technical Communication (ISTC), which praised the team’s submission:
“The entry is so readily usable and consistently informative; it includes good features such as links to relevant external documentation, the ability to copy and paste example code, and direct writing style to match the product framework”.
The Kedro team is made up of developers and data scientists who take care to write copy that can be understood by fellow developers and data scientists. We use a documentation process we are all familiar with and work with markdown files in our Github repository, rather than inside a CMS or wiki. Every pull request that touches documentation follows the same process as for code, running through continuous integration testing to ensure that we do not publish pages with broken links or missing graphics.
Because we are not trained proof-readers we do get it wrong sometimes, so across the team we continually review our own and each others’ published work, suggesting amendments where needed. We will never stop trying to improve our documentation capabilities and believe that we can always strive to refine our skillset but receiving ITSC recognition last year was highly encouraging and shows that we are on the right track.
Whether you are writing code or technical documentation, many of the same rules apply; shorter and clearer is nearly always better than long and complex. If you follow the above rules in your writing, your communication will not only become more coherent, it will powerfully deliver its intended impact. Remember that you are putting this documentation together for the benefit of others — and accessible, clear language will enhance effective collaboration across a project and assist end-users in utilising the solution.
We’re always interested in feedback on Kedro’s documentation — if you have a comment or want to suggest improvements, please do let us know in the comments section below or via Github.
Katherine Holden
Katherine joined techUK in May 2018 and currently leads the Data Analytics, AI and Digital ID programme.