tcworld China 2021 — A Complete Docs as Code Workflow

Date: September 17, 2021
Event: tcworld China conference
Speaker: Diana Lakatos, Director of Documentation at platformOS

Based on the success of our presentation at the Evolution of TC 2021 conference, tcworld China invited us to talk about the docs as code workflow we built for our developer portal and answer questions from the audience about the topic.

tcworld China 2021

tcworld organized the seventh international conference for technical communicators and language professionals in China. Their primary goal is to bring together national and international leaders and professionals as well as friends and partners of technical communication in an open dialogue, to exchange brilliant ideas, to develop solutions for specific TC challenges.

At tcworld China 2021, local and international TC experts shared their experiences and best practices with solutions for China-specific challenges, to exchange the latest information in the Technical Communication industry. Participants had the opportunity to participate in presentations, workshops, and interactive sessions.

The main conference topics covered:

• Intelligent information
• Localization
• Information development
• Software documentation
• User assistance
• Content marketing
• Regulations and standards

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.

Watch the recording of our talk

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