OSS Docs and How to Scale Them: Common Themes From the CNCF Ecosystem

The presentation discusses the importance of documentation in open-source projects and provides tips for managing documentation as the project grows.

• Documentation is the truth of the project and must be accurate and maintained
• As the project grows, it is important to involve the community in contributing to documentation through good first issues
• Scope documentation tasks well and consider moving docs to their own repo
• Implement content policies, such as beta and alpha policies and documenting API limitations and out-of-scope functionality
• Consider automating documentation processes, such as release notes and CLI flags
• Address hard problems, such as localization and containerization
• Versioning docs is important for managing changes over time

The speaker shared that in a previous project, they had neglected documentation until a new contributor pointed out that the documentation was inaccurate and caused them to waste time. This experience highlighted the importance of documentation and inspired the speaker to prioritize it in future projects.

The first interaction new users have with an open source project is documentation. Documentation is a key adoption driver for open source projects, and the professionalism, completeness, and presentation of your documentation has a dramatic impact on how your project is perceived by potential users. How do you get your project’s docs to shine? How do you set your tooling up to support you as you grow? What metrics can we use to evaluate the quality of a project’s documentation? In this talk we use data from the CNCF’s documentation assessment service to give an overview of common issues we see with open source project’s documentation and how to resolve them. She breaks out these issues by project maturity and community size, and discusses how a given project’s documentation needs change as it grows. Finally, we discuss how projects can best get documentation done as they grow, based on what we’ve seen work in various CNCF project communities.Click here to view captioning/translation in the MeetingPlay platform!