CNCF and Expert Support: Scaling documentation quality across CNCF projects through best practice education, expert analysis, and writing assistance
Executive summary
As part of its ongoing collaboration with Expert Support, CNCF advanced documentation quality across multiple open source projects by refining and applying a documentation maturity analysis framework aligned with CNCF project maturity standards (the progression from Sandbox to Incubating status, before finally reaching the Graduated level).
Led by CNCF’s Tech Docs group, in collaboration with Expert Support Senior Technical Writer David Welsch, the initiative focused on evaluating documentation, identifying structural gaps, and translating findings into actionable GitHub issues maintainers and contributing writers could use to improve documentation sustainably.
“The goal was to lower the barrier to improving the documentation,” said Welsch.
“There’s no shortage of opinions about what good documentation looks like.” says CNCF’s Head of Mentorship & Documentation, Nate Waddington. “What’s been missing is a rigorous, repeatable way to get there, one that meets projects where they are and gives contributors something they can act on. That’s what we’ve built.”
Projects used
By the numbers
250+
CNCF projects supported through scalable documentation improvement initiatives
2
free training courses created to strengthen documentation skills across the community
12
Litmus Chaos documentation issues identified, with 25% completed within weeks
Challenge
CNCF projects often evolve rapidly, while documentation can lag behind code maturity. Although maintainers recognize documentation as critical, teams can struggle to define priorities or determine how to improve documentation effectively.
Analyses conducted through the Documentation Assistance Program consistently surfaced common challenges:
- Missing user analysis and audience assumptions
- Weak getting-started experiences
- Imbalance across conceptual, reference, and task-based documentation
- Overloaded documents containing multiple knowledge types
- Limited contributor guidance for onboarding maintainers and writers
These patterns informed project-level recommendations as well as refinements to CNCF’s documentation rubric.
Partnership goals: The Documentation Assistance Program
Through the Documentation Assistance Program, CNCF and Expert Support set out to strengthen documentation as a scalable community capability across the cloud native ecosystem by focusing on seven goals:
- Raise documentation quality across CNCF projects
Advance the quality of technical documentation across CNCF projects and support documentation as a core component of project maturity.
- Build documentation literacy across the community
Establish foundational literacy in technical documentation for everyone in the CNCF community—from maintainers to contributors to new project teams.
- Help Sandbox projects start strong
Introduce documentation values and competencies early so Sandbox projects can build strong foundations for scalable documentation as their software and communities grow.
- Apply documentation maturity criteria in practice
Evaluate selected CNCF projects against documentation maturity criteria and translate findings into practical improvement opportunities.
- Turn analysis into action
Make informed recommendations and open documentation-centric issues in project GitHub repositories to help projects prioritize improvements.
- Support Maintainers and contributing writers
Help maintainers and contributing writers close issues, improve workflows, and strengthen documentation sustainably.
- Evolve CNCF’s documentation rubric
Refine and improve CNCF’s documentation rubric to reflect the real-world needs of new and prospective community members.
Solution
To support documentation improvement across 250 CNCF landscape projects (https://landscape.cncf.io/stats), CNCF and Expert Support developed a three-part approach:
Community education
CNCF funded the development of two free Linux Foundation training courses to build foundational documentation literacy:
- Open Source Technical Documentation Essentials (LFC111)
https://training.linuxfoundation.org/training/open-source-technical-documentation-essentials-lfc111/ - Creating Effective Documentation for Developers (LFC112)
https://training.linuxfoundation.org/training/creating-effective-documentation-for-developers-lfc112/
Together, these courses provide foundational guidance in technical documentation best practices.
Early support for Sandbox projects
CNCF and Expert Support created a white paper and developed a workshop to help early-stage projects establish scalable documentation practices. By applying well-established best practices early, projects can build a strong documentation foundation that grows with their software systems and communities over time.
The white paper outlines key concepts stakeholders should understand to organize documentation efforts effectively from the start and helps early-stage projects adopt practices designed to scale.
This work introduces key concepts stakeholders can use to organize documentation efforts early.
Documentation assistance and maturity analysis
CNCF and Expert Support refined a repeatable methodology for evaluating and improving documentation:
Documentation Assistance Model
https://github.com/cncf/techdocs/blob/main/docs/assistance.md
Analysis Primer
https://github.com/cncf/techdocs/blob/main/docs/analysis/howto.md
Documentation Criteria / Rubric
https://github.com/cncf/techdocs/blob/main/docs/analysis/criteria.md
Analyses evaluate:
- Product documentation
- Contributor documentation
- Infrastructure
Each analysis produces actionable GitHub issues in addition to reports, helping projects prioritize improvements while informing refinement of the CNCF documentation rubric.
Project highlights
Knative (https://knative.dev/)
The challenge: Documentation analysis identified gaps in conceptual clarity and onboarding materials, including missing conceptual overviews and unclear getting-started guidance
The solution: Through the Documentation Assistance Program, CNCF opened GitHub issues that translated those findings into actionable improvements for maintainers and contributors.
The impact: A conceptual overview was drafted, completed, and merged, and onboarding documentation was assigned to writers. A strong uptake of recommendations followed, with Expert Support writer Bruce Hamilton funded to implement fixes, illustrating how actionable issues combined with project ownership and budget can drive measurable progress.
Vitess (https://vitess.io/)
The challenge: Documentation analysis was conducted to evaluate alignment with CNCF maturity documentation standards, with opportunities identified across user and contributor documentation.
The solution: The Documentation Assistance Program delivered detailed recommendations and issue-level guidance to help improve documentation and provide maintainers with actionable next steps.
The impact: Community engagement with these issues has so far been limited. The work reinforced an important finding: identifying a capable technical writer, either within the community itself or funded by the community and/or foundation, appears to be the fastest and most reliable path to close issues and deliver benefits to the community.
Litmus Chaos (https://litmuschaos.io/)
The challenge: An ongoing documentation engagement spanning 2024–2025 identified opportunities to strengthen documentation for administrators and engineers running resilience experiments.
The solution: Through the Documentation Assistance Program, issues were opened and recommendations provided to improve documentation supporting chaos engineering use cases.
The impact: Three of the twelve issues identified in the analysis have been completed, and most of the others were picked up or assigned to contributors within a few weeks of being opened. Volunteer contributors have already advanced documentation improvements, while the work also demonstrated that funding a capable technical writer can further heighten positive impact across the Litmus Chaos community.
Backstage (https://backstage.io/)
The challenge: Documentation analyses initiated in 2023 identified an opportunity to extend and improve documentation analysis methodology across a mature project while aligning it more closely with the CNCF maturity model.
The solution: Through continued support in 2025, the CNCF rubric was retained across legacy projects and maintainers while the methodology was improved, extended to include issue creation, and used to guide documentation improvements.
The impact: Many recommendations were implemented, including a new documentation landing page and restructured overviews. These improvements have enhanced user experience across the Backstage community and demonstrate the long-term value of sustained collaboration between CNCF and Expert Support in driving durable documentation quality gains.
Additional 2025 support included etcd and TUF, where Welsch advised maintainers executing prior analyses.
The project’s impact
Through education, maturity analysis, issue creation, and writing support, the partnership between CNCF and Expert Support helped establish a practical and repeatable approach to documentation improvement across CNCF projects.
Key outcomes included:
- Greater documentation literacy across the community
- Actionable improvement pathways for maintainers and contributors
- Refinement of CNCF’s documentation rubric based on real-world project needs
- Demonstrated value of combining analysis with implementation support
Looking ahead, CNCF and Expert Support are now working to extend and enhance these efforts with the very latest techniques and best practices to leverage modern AI-based tools and workflows.
Key takeaways
By providing education about best practices, and transforming a maturity-model rubric into a practical, repeatable process, Expert Support has enabled CNCF to establish and implement a scalable, pragmatic pathway to help improve technical documentation across the extensive CNCF landscape.
This approach – and the partnership itself – establishes the foundations for technical documentation improvement across CNCF, and beyond to the rest of the open source ecosystem.