Evolution of TC 2021 — A Complete Docs as Code Workflow

Date: June 10, 2021
Event: Evolution of TC 2021 conference
Speaker: Diana Lakatos, Director of Documentation at platformOS

In our session at Evolution of TC 2021, we showed the real-life example of the complete docs as code workflow that we developed for our UKTC Awards winning developer portal; how we produce and manage content, use plain text formats, a style guide and templates, track issues, and review and edit contributions from a fully remote team and community.

Evolution of TC 2021

Evolution of TC is the annual conference organized by tekom (the European Association for Technical Communication) covering innovations in software documentation. This year the conference took place as an online event. For around 200 attendees from 26 countries, international expert speakers covered topics such as information modeling, API documentation and continuous delivery, UX writing, metadata/taxonomy, and much more.

A Complete Docs as Code Workflow — A Case Study of the platformOS Developer Portal

We presented a case study of the platformOS documentation and related docs as code workflows and processes. This is a summary of what we talked about:

• Introduction: to put everything in context, we started with introducing our team, our community, and the documentation site itself.
• Docs as code: what does it mean, what are the reasons for following a docs as code approach and what are the key goals for an organization implementing it. This was a theoretical overview of docs as code in preparation for the examples and the more in-depth explanations that followed.
• Content: how we produce and structure content, including how we help others to contribute content to our documentation. We presented examples of our style guide, contributor guide, and templates. We also discussed why we chose the Markdown format and how we use it.
• Editorial workflow: we described the steps in our editorial workflow in detail, including how we use GitHub, how we track issues, and how the review process works.
• CI/CD: finally, we discussed what continuous integration and continuous delivery mean and how each concept applies to documentation, with examples of how we built our CI/CD workflow with GitHub Actions, and how we run automated tests as part of our CI/CD workflow.

At the end of the presentation we hosted a Q&A session, where attendees filled the allocated half hour slot with relevant and interesting questions. We are thrilled to have received overwhelmingly positive feedback to our presentation. Attendees shared that they had found the session very insightful and engaging with one person noting that they’d never understood docs as code as well as they do now since attending. In sharing our experience we hope to help others on their journey of building effective developer documentation sites, so it was rewarding and reaffirming to hear our audience found it insightful.

Watch the recording of our talk

If you have registered for the Evolution of TC conference, you can download the presentation and watch the recording of our talk.