Bridge the Gap To OSS Adoption With Documentation: A Kubernetes Story - Natali Vlatko & Divya Mohan

Bridge the Gap To OSS Adoption With Documentation: A Kubernetes Story

Speakers: Natali Vlatko, Open Source Architect and OSPO Lead at Cisco; Divya Mohan, Principal Technology Advocate at SUSE

Conference: KubeCon EU

YouTube: https://www.youtube.com/watch?v=Q40yLLLIW9Q

Overview

In this insightful KubeCon EU presentation, Natali Vlatko and Divya Mohan, both co-chairs of the Kubernetes SIG Docs special interest group, delved into the critical role of high-quality documentation in fostering the adoption and sustained growth of open-source projects. Focusing on Kubernetes, a colossal project second only to Linux in scale and utilized by an estimated 71% of Fortune 100 companies as their primary container orchestration tool, the speakers shared their strategies for creating, maintaining, and evolving documentation that effectively serves a diverse global user base. The talk highlighted that while Kubernetes' documentation receives both praise and criticism, the lessons learned in its continuous improvement are invaluable for any project aiming to enhance its user experience and bridge the gap to wider adoption.

The core of the discussion centered on the inherent challenges of documenting a rapidly evolving, technically complex, and community-driven project. Vlatko and Mohan articulated how the Kubernetes SIG Docs team navigates the "proximity problem" – the tension between technical accuracy and user readability – by establishing clear ownership models and fostering a culture of community contribution. They introduced key principles such as the Minto Pyramid Principle and scannable text techniques, emphasizing the importance of a consistent voice and direct language to make complex information accessible to users of varying skill levels.

This presentation is particularly relevant for open-source project maintainers, technical writers, developer advocates, and anyone interested in the dynamics of large-scale community-driven documentation. It provides a blueprint for improving documentation efforts, not just within the open-source realm but also for proprietary software, by focusing on user needs, structured content, and an empowered contributor community. The speakers' experience with Kubernetes offers a unique perspective on managing documentation for a project that has become a cornerstone of modern cloud-native infrastructure, underscoring that excellent documentation is not merely a feature, but a fundamental driver of adoption and success.

Background

▶ Watch: Introduction and Kubernetes documentation context (0:00)

The journey of an open-source project from niche utility to widespread adoption is often paved with good intentions, but frequently hampered by inadequate or inaccessible documentation. As Vlatko and Mohan highlighted, research consistently confirms that documentation quality is one of the most significant factors influencing a company's decision to adopt an open-source project. This challenge is amplified for projects like Kubernetes, which, despite its immense success and status as the de facto standard for container orchestration, presents a steep learning curve for many users. The project's rapid development cycle, with three major releases per year, coupled with its vast and intricate feature set, creates a continuous demand for up-to-date, accurate, and user-friendly documentation.

A central theme explored in the talk is what the speakers termed the "proximity problem." This refers to the inherent dilemma in documentation efforts: should the documentation team be embedded within technical project teams, ensuring deep technical accuracy, or should they function as a separate technical writing team, prioritizing user experience and readability? For Kubernetes, the answer lies in a nuanced division of labor within its Special Interest Group (SIG) structure. The SIG Docs team, co-chaired by Vlatko and Mohan, primarily advocates for the user, focusing on the how of documentation – its structure, readability, and overall usability. Conversely, the what of the technical content, specifically for new features and enhancements, is owned by the KEP (Kubernetes Enhancement Proposal) owners – the technical experts responsible for developing and implementing those features. This separation ensures that while the content remains technically sound, its presentation is tailored for optimal user consumption, addressing the challenge of balancing expert knowledge with user-centric delivery.

Prior efforts in the Kubernetes community have consistently sought to refine this collaborative model. The speakers referenced a previous KubeCon talk titled "How we navigate collaboration across docs, across SIGs with docs in the project," which provided further insights into the intricate workflows and communication strategies employed to bridge the gap between technical contributors and documentation specialists. This ongoing commitment to improving documentation processes reflects a deep understanding within the Kubernetes community that the project's accessibility, and thus its continued growth, hinges significantly on the quality and maintainability of its user guides, tutorials, and reference materials. The problem, therefore, is not merely to have documentation, but to have documentation that is strategically designed, continuously updated, and collaboratively maintained to meet the diverse needs of its global user base.

Key Findings

▶ Watch: Overview of talk agenda and key topics (3:40)

The talk unveiled several key findings and principles that are instrumental in bridging the gap to OSS adoption through effective documentation, particularly within the context of a project as vast as Kubernetes:

1. Dual Ownership Model for Documentation Quality: Kubernetes SIG Docs effectively addresses the "proximity problem" by establishing a clear division of responsibility. SIG Docs represents the users, focusing on the how – ensuring documentation is readable, usable, and consistently structured with a clear flow. KEP owners (Kubernetes Enhancement Proposal) represent the technical experts, owning the what – ensuring the technical content for features (alpha, beta, graduated) is accurate. This collaborative approach, validated by technical LGTMs (Looks Good To Me) from KEP owners, ensures both technical rigor and user-centric design.

1. The Power of Consistent Voice and Direct Language: A subtle yet profound finding is the impact of documentation's voice and tone. The Kubernetes documentation consciously employs active voice and directly addresses the user as "you," avoiding first-person or passive voice. This approach, enshrined in their continuously updated style guide, empowers the user, positions them as the subject, and makes complex instructions easier to grasp. The emphasis on direct language over "Shakespearean prose" ensures simplicity and easy consumption, especially crucial for a project that needs to be translated into 16 different languages.

1. Minto Pyramid Principle for Information Structure: To combat the reality that 79% of online readers strictly skim content, SIG Docs applies the Minto Pyramid Principle. This framework structures information with the most important takeaway at the very top, followed by increasingly granular details. This "pyramid" approach, combined with scannable text principles like prominent subheadings and bullet points, optimizes documentation for quick comprehension and caters to diverse user personas, from beginners to administrators, and even those cramming for certification exams like CKA and CKAD.

1. Community-Driven Development is Non-Negotiable: Given Kubernetes' scale, rapid evolution (three releases per year), and extensive localization efforts (16 languages), the documentation is "never perfect or complete." The talk emphasizes that continuous contributions from the community are essential. The best way to contribute is by using the docs and identifying areas for improvement.

1. Embracing "Good Enough" PRs and Consolidating Edits: To facilitate community contributions and reduce friction, SIG Docs actively encourages PRs that are "good enough" and represent an improvement, rather than demanding perfection from new contributors. However, this is balanced by recognizing the engineering cost of every contribution. Trivial edits (e.g., single typos) are encouraged to be bundled with more substantial improvements (e.g., reformatting a paragraph into bullet points) to maximize the impact of each review and merge cycle. This approach prioritizes iterative improvement and efficient use of maintainer time.

Technical Deep Dive

▶ Watch: Introduction to the 'proximity problem' in docs (4:10)

The Kubernetes documentation ecosystem, managed primarily by SIG Docs, is a sophisticated operation designed to support a project of immense scale and complexity. At its core, the system addresses the inherent tension between maintaining technical accuracy and ensuring user accessibility through a well-defined ownership model and established processes.

The proximity problem is resolved through a clear delineation of responsibilities. SIG Docs serves as the advocate for the user, taking ownership of the how documentation is presented. This includes establishing and enforcing the documentation style guide, designing the overall information architecture of kubernetes.io/docs, and ensuring a consistent user experience across various content types. Their focus is on readability, usability, and flow, catering to a spectrum of users from absolute beginners seeking "concepts" and "how-to" guides to experienced system administrators and architects requiring "API reference documentation" and advanced conceptual material.

The what of the documentation—the technical content itself—is primarily owned by the KEP (Kubernetes Enhancement Proposal) owners. KEPs are the formal mechanism for introducing new features and significant changes into Kubernetes. As features progress through their lifecycle (alpha, beta, graduated), their respective KEP owners are responsible for ensuring the technical accuracy of the accompanying documentation. This is enforced through a mandatory technical LGTM (Looks Good To Me) process, where KEP owners must review and approve the documentation associated with their features before it can be merged. This ensures that the documentation precisely reflects the functionality and behavior of the underlying code, preventing discrepancies that could lead to user frustration or misconfiguration.

The structure of kubernetes.io/docs is carefully designed to accommodate different skill levels and information needs. Users can find:

• Concepts: Explanations of core Kubernetes components and ideas.
• Tasks/How-tos: Step-by-step guides for common operations, often tailored to specific operating systems or tooling.
• Tutorials: More comprehensive, hands-on learning paths (though former Katakoda tutorials had to be removed due to external issues).
• API Reference: Detailed documentation of Kubernetes API objects, crucial for developers and advanced users.

A cornerstone of the documentation's effectiveness is the Kubernetes Documentation Style Guide. This guide is a living document, constantly updated to reflect best practices and community feedback. Key tenets include:

• Active Voice: Instructions are always framed actively, placing the user as the agent (e.g., "You create a Pod" instead of "A Pod is created").
• Direct Language: Avoiding jargon, flowery prose, and overly complex sentence structures to ensure clarity and ease of translation.
• Addressing the User as "You": Fosters a direct, empowering relationship between the documentation and the reader.
• Site-Relative Links: Encouraged for better maintainability and navigation.

To address how users consume information online, SIG Docs heavily relies on the Minto Pyramid Principle and scannable text principles. The Minto Pyramid Principle dictates that information should be structured from the general to the specific: the most important takeaway is presented first, followed by supporting details and increasing granularity. This allows users to quickly grasp the core message before delving into specifics. Complementing this, scannable text principles are employed throughout the documentation. These include:

• Clear Subheadings: Breaking down content into manageable, logically grouped sections.
• Bullet Points and Numbered Lists: For presenting sequential steps or distinct items, improving readability and retention.
• Bold Text: Highlighting key terms and concepts on first mention.

The global nature of Kubernetes necessitates extensive localization efforts, with documentation available in 16 different languages (including English). This presents a significant technical and logistical challenge, as changes to the English documentation inevitably create a "natural lag" for localization teams to catch up. Furthermore, versioned documentation is maintained to support different Kubernetes releases, ensuring users can access relevant information for their specific cluster versions.

A critical area currently undergoing a major revamp is the API reference documentation. This sub-project within SIG Docs is actively seeking community contributions, particularly from individuals proficient in Go and Python, as the generation process involves complex Go code and various batch scripts calling Python scripts. This revamp aims to improve the accuracy, consistency, and usability of this vital resource, which is often over a thousand pages long if printed, highlighting the sheer scale of the project.

Finally, the talk underscored that documentation is a continuous, community-driven effort. Kubernetes SIG Docs encourages all users to become "drive-by contributors" by submitting Pull Requests (PRs) for improvements, no matter how small. They advocate for accepting "good enough" PRs that demonstrably improve the documentation, rather than holding out for perfection, to reduce the barrier to entry for new contributors. However, they also encourage bundling small, "trivial edits" (e.g., a single typo fix) with more substantial improvements (e.g., reformatting a section with bullet points) to maximize the impact of each contribution and acknowledge the engineering cost associated with the review and merge process. Feedback mechanisms, such as "Was this page helpful? Yes/No" buttons and direct links to edit pages or create issues, are integrated into kubernetes.io to continuously gather user input and identify areas for improvement.

Demo / Proof of Concept

▶ Watch: Balancing technical accuracy and user readability in docs (6:00)

This technical article is based on a conference talk that focused on the principles, processes, and community-driven development of documentation for large open-source projects, specifically Kubernetes. The presentation itself did not include a live technical demonstration or a proof of concept in the traditional sense of showcasing code, a vulnerability exploit, or a new tool. Instead, the "demonstration" was an articulation of the philosophical and practical approaches taken by the Kubernetes SIG Docs team to improve documentation quality and foster adoption.

The speakers used examples from the Kubernetes documentation website (kubernetes.io/docs), referencing its structure, style guide, and feedback mechanisms, to illustrate their points. For instance, they showed screenshots of the "Was this page helpful?" feedback widget and the "Edit this page" links, highlighting how these features encourage community engagement and continuous improvement. While not a live coding demo, these visual references served to concretely exemplify the strategies discussed for enhancing documentation usability and maintainability.

Defensive Implications

▶ Watch: SIG Docs owns 'how' not 'what' of documentation content (6:40)

While the talk "Bridge the Gap To OSS Adoption With Documentation: A Kubernetes Story" does not directly address cybersecurity vulnerabilities or traditional defensive strategies, its insights have significant indirect implications for the security posture and overall health of any open-source project, including Kubernetes. Effective documentation acts as a critical first line of defense against common pitfalls that can inadvertently lead to security vulnerabilities or operational instability.

Firstly, preventing misconfiguration and misuse is a primary defensive implication. Clear, accurate, and user-friendly documentation ensures that users, from beginners to experienced administrators, correctly understand how to deploy, configure, and manage Kubernetes clusters and applications. Misconfigurations are a leading cause of security incidents in cloud-native environments. If documentation is confusing, incomplete, or technically inaccurate, users are more likely to make errors in setting up network policies, role-based access control (RBAC), secure communication, or resource limits. By adhering to principles like the Minto Pyramid Principle and scannable text, SIG Docs makes it easier for users to quickly find and correctly interpret crucial security-related configuration steps, thereby reducing the attack surface introduced by human error.

Secondly, fostering proper adoption and secure practices is enhanced by quality documentation. For an enterprise to adopt Kubernetes, trust in its stability, reliability, and security is paramount. Comprehensive and easy-to-understand documentation builds this trust. If the documentation effectively explains security features, best practices, and potential risks, it empowers users to implement Kubernetes securely from the outset. This "defensive" posture is about proactive education, ensuring that the project's security capabilities are not just present but are also discoverable and actionable by its users. The consistent voice and direct language advocated by SIG Docs make complex security concepts more digestible, enabling broader understanding and implementation of secure patterns.

Thirdly, enabling community contribution to security documentation is another vital aspect. The emphasis on "good enough" PRs and community-driven development extends to security-related content. If a user identifies an ambiguity in a security guide or a missing step in a hardening tutorial, the simplified contribution process encourages them to submit improvements. This crowdsourcing of knowledge helps keep security documentation current with evolving threats and best practices, effectively creating a distributed "security documentation team" that continually strengthens the project's defensive posture. The ability to quickly update and clarify documentation, as opposed to waiting for internal teams, provides an agile response mechanism to emerging security concerns.

Finally, reducing support burden and improving incident response indirectly contributes to security. When users can find answers efficiently in well-structured documentation, it reduces the need for direct support, freeing up maintainers and core contributors to focus on critical development and security tasks. In the event of an incident, clear documentation can guide users through troubleshooting, mitigation steps, or understanding the impact of specific vulnerabilities, enabling a faster and more effective response. This operational resilience, facilitated by robust documentation, is a key component of a comprehensive defensive strategy for any large-scale open-source project. In essence, while not a direct security tool, quality documentation is an indispensable enabler of secure deployment, operation, and community engagement, serving as a critical preventative measure against a wide array of operational and security challenges.

Key Takeaways

• Documentation is a Critical Driver for OSS Adoption: High-quality, user-friendly documentation is not just a feature; it's a primary factor influencing the decision of enterprises and individuals to adopt an open-source project like Kubernetes.
• Separate Ownership for Content vs. Structure is Key: To balance technical accuracy with user experience, establish a clear division where technical experts (KEP owners) own the "what" (technical content) and documentation specialists (SIG Docs) own the "how" (structure, readability, and user flow).
• Consistency in Voice and Language Matters: Employ active voice, direct language, and address the user as "you" to empower readers and make complex information more digestible. A constantly updated style guide is essential for maintaining this consistency.
• Structure Information for Scannability: Utilize principles like the Minto Pyramid Principle (most important info first) and scannable text techniques (subheadings, bullet points) to cater to how users actually read online, enabling quick information retrieval for diverse personas.
• Foster a "Good Enough" Community Contribution Culture: Encourage continuous community contributions by accepting "good enough" PRs that improve the documentation, rather than demanding perfection. However, encourage bundling trivial edits with more substantial improvements to optimize the "engineering cost" of reviews.
• Documentation is Never "Done": Given the rapid evolution of open-source projects, documentation must be viewed as a continuous, iterative process, requiring constant updates, localization efforts, and ongoing community engagement.

About the Speaker(s)

Natali Vlatko is an Open Source Architect and OSPO Lead at Cisco. With a background in web development and engineering management, she brings a unique blend of technical acumen and leadership experience to the Kubernetes community. Natali is one of the co-chairs of Kubernetes SIG Docs, where she helps steer the project's documentation efforts. She is also actively involved in the Linux Foundation's To-Do Group steering committee, a community of OSPO (Open Source Program Office) experts focused on sharing best practices for open-source program management within companies.

Divya Mohan serves as a Principal Technology Advocate at SUSE. Her career journey includes a decade in sysadmin roles, followed by transitions into project management and developer advocacy, culminating in her current role. Divya is also a co-chair of Kubernetes SIG Docs, contributing significantly to the strategic direction and quality of Kubernetes documentation. Additionally, she is a member of the Kubernetes Code of Conduct Committee, reflecting her commitment to fostering an inclusive and respectful community environment.