How the Kedro team built award-winning documentation

Kedro was created by a team at QuantumBlack Labs, AI by McKinsey. We are a small team of engineers, plus some designers and myself, a technical writer.

The Kedro documentation (https://docs.kedro.org) and Kedro blog (https://blog.kedro.org) are crucial in providing information to this diverse user base. We strive to keep all our content simple, friendly, and functional. The documentation was written collaboratively by us all over a period of about four years since Kedro was open-sourced and, like Kedro itself, it is still under development.

We use a ‘docs-as-code’ workflow that creates documentation using the same processes as the rest of the Kedro codebase, giving it the same attention, care, and rigour as any other software development task. We write in Markdown and use Git for version control; in effect, the documentation is reviewed, tested, and deployed in the same way as code. Our processes mean that there are several sets of eyes on every change to the docs to ensure accuracy, up-to-date information, and consistent quality. We follow agile methodologies to prioritise docs updates, and the QuantumBlack Labs organisation has a particularly strong tradition of product management, so we regularly conduct user research and study usage analytics to determine where to improve and enhance our content. 

We had previously entered the Technical Communication UK (TCUK) Awards in 2020 when our documentation was still in the early stages of development. In that year, we won a merit award for our beginner ‘get started’ documentation, which had encouraged me to develop the tone and style that we used in that section for use across all our content. 

In 2023, I decided it was time to re-enter the awards to get an extra level of feedback and a professional evaluation on our entire documentation set. I crafted and submitted a brief description of our audience and the purpose of the documentation, as well as how we use our blog to share insights about Kedro. It was the perfect time to submit the entry as Kedro had just been rebranded and our docs had been refreshed with a new table of contents.

I was delighted to find out a few weeks after entering that we had been shortlisted for the award and so happy to attend the conference in person in September 2023. It was a great experience to be able to network with other technical communicators and to learn about the latest trends in the industry. One of the session leaders, David Bailey, covered the docs-as-code methodology and I have come away from that talk inspired to investigate some of the tools his team are using at Snyk. 

It was a proud moment when the Kedro docs were announced as the overall winner of the UK Technical Communication Awards 2023, and I could hardly concentrate sufficiently to read the judges' comments on the screen.

As the sole technical writer in our team, it was brilliant to know that I am steering the rest of the team in the best possible direction and that we are all collaborating to build something worthy of this award. 

The documentation and the blog are very impressive in the fulfilment of their brief: The simple, friendly and functional message was very evident throughout the documentation. The layout was really clear. The navigation on the left was simple; the breakdown from beginners to expert was particularly well executed. The use of direct language with consideration given to different levels of expertise is very effective.

Judge feedback, UK Technical Communication Awards 2023

We are looking forward to continuing to extend our documentation and blog in the future. Our ultimate objectives are to support skill development, raise awareness, and cultivate a thriving and engaged Kedro community, which ultimately benefits the project and the growing field of data science.

If you have any thoughts or comments on how we can improve the Kedro doc, please do get in touch via our Slack organisation!