We discuss how "docs as code" works with static site generators and version control systems like Git to streamline approvals and content reuse. The conversation also covers the role of AI in documentation, highlighting the importance of human oversight for AI-generated content. We wrap up with advice for new technical writers and recommend helpful resources.
1. About Vladimir
Our guest for this episode is Vladimir Izmalkov, a brilliant technical author at Canonical with over 15 years of experience specializing in developer documentation and technical communication.
Beyond his core role, he's actively involved in mentorship, having been recognized as a top 10 mentor in his category on ADPList. Vladimir identifies himself as a "technical technical writer," gravitating towards tooling, software engineering, and understanding how technologies work. He expresses a particular love for being a "pathfinder" for new products and features, comparing it to building a clear bridge through a "jungle" of unknown information for users.
Ready to level up your documentation ?,
In this conversation, we discuss:
This episode is packed with invaluable insights into modern documentation practices. Here’s a quick rundown of what we covered:
Open Source Documentation at Canonical: Vladimir sheds light on Canonical's robust policies for community engagement. Their documentation is publicly available on GitHub, actively encouraging external contributions. For newcomers, the Canonical Open Documentation Academy offers simpler tasks and mentorship, serving as a fantastic way for new technical writers to build their portfolio.
Understanding "Docs as Code": We break down this powerful approach, explaining how it treats documentation content just like source code. This means using plain text files and a mechanism to generate the final output (typically a website). The beauty? Technical writers get to leverage professional tools used by software developers, like Integrated Development Environments (IDEs) and, crucially, version control systems like Git, for efficient collaboration, tracking changes, and automation.
How "Docs as Code" Works: Vladimir details the workflow: source content in text files is processed by a "static site generator" (like Sphinx or Hugo), which acts like a compiler, to produce a website. The static site generator's template handles the design, letting writers focus purely on content. Plus, with CI/CD pipelines, changes pushed to Git repositories can be automatically built and published.
Structuring Documentation in "Docs as Code": The structure is largely determined by the chosen static site generator, often relying on configuration files to define navigation menus that link to specific source text files. This allows for clear organization, even with numerous individual files.
Alternatives to "Docs as Code": We explore other options, from simple text editors saving to PDF (like MS Office), to proprietary systems like MadCap Flare or Help & Manual, often favored by regulated industries for their robust, standardized environments. While "docs as code" requires initial setup, tools like Pandoc can assist with content migration.
When to Use "Docs as Code": It's most suitable for teams documenting software, especially those with engineers who can assist with setup. It's also ideal for rapid documentation deployment, sophisticated projects with multiple collaborators, or when robust version control is critical. Smaller teams might find other methods more fitting due to the initial technical investment.
API Documentation and Automation: Vladimir emphasizes that API references (commands, endpoints, parameters) should be automated and autogenerated with minimal manual effort (using tools like Open API/Swagger). However, he stresses that API documentation goes beyond references, including tutorials, how-to guides, and conceptual explanations to onboard users faster and reduce errors. He advises prioritizing user experience and tailoring the detail level to the audience and product context. For specific cases like fintech/banking APIs, security requirements are paramount.
Approval Processes in "Docs as Code": "Docs as code" leverages version control systems like Git for approvals, mirroring software development workflows. Changes are submitted via pull requests (PRs) or merge requests, allowing reviewers to discuss, request modifications, and approve before merging. This automated process (often on platforms like GitHub or GitLab) ensures necessary approvals are met, saving significant time compared to traditional manual reviews.
Technical Savvy for Technical Writers: The role of a technical writer is incredibly diverse. While some focus on linguistic aspects, others, like Vladimir, are more technically inclined. For "docs as code," technical writers need at least basic knowledge of version control systems and software development life cycles. The initial setup can often be handled by software engineers, letting writers focus on content creation.
Reusable Content and Automation Features: "Docs as code" shines with reusable content via "include directives" in markup languages like Mist Markdown. This "single-source" approach ensures consistency for repeated warnings or instructions and automatically updates content across all instances when the original source is modified. Advanced IDEs offer powerful search and replace functions, and CI/CD pipelines can automate content quality checks for spelling, broken links, and inclusive language before publishing.
Role of AI in Documentation: Vladimir differentiates between automation and using AI, strongly advising human oversight for all AI-generated content. He uses AI for specific tasks like rewriting paragraphs, shortening text, or suggesting synonyms. He cautions that over-reliance on AI can sometimes consume more time than traditional writing. He also notes that users are leveraging AI to summarize documentation, suggesting writers should strive for concise, direct documentation to reduce this need.
Advice for New Technical Writers: Vladimir acknowledges the tough competition in the IT field, especially for junior roles, partly due to AI's impact on job applications and filtering. He advises that while getting started can be challenging, reaching mid or senior levels makes it easier to compete, as human insight and problem-solving skills become more valued over AI-generated text. He highly recommends exploring DIATAXIS for documentation structuring and the Canonical Open Documentation Academy for open-source contributions as excellent starting points.
3. Where to find more about Guests
Want to connect with Vladimir or learn more?
You can find Vladimir on LinkedIn for professional communication about documentation.
He also offers free mentorship sessions on ADPList, so feel free to find him there!.
4. Referenced:
Here are some key concepts, tools, and resources mentioned in our conversation:
Share this post