Becoming a keystone project
The Good Docs Project is growing into a keystone project for software ecosystems. Read on to learn about what a keystone project is and why they matter.
The Good Docs Project is growing into a keystone project for software ecosystems.
What’s a Keystone Project?
In architecture, a masonry arch cannot be self-supporting until the keystone is placed. This stone locks together the whole structure.
The concept is also found in ecology. A keystone species is an organism that helps define an entire ecosystem - and it has a disproportionate influence on the ecosystem around it. Bees are a keystone species. Without bees, flowers don’t get pollinated, plants don’t reproduce, animals starve, and the ecosystem collapses.
In the technology domain, Git can be thought of as a keystone project. Its version control underpins many software projects, meaning it has a disproportionate positive impact on the software ecosystem.
Is documentation disproportionately impactful?
Yes. Time and again, surveys call out documentation quality as a key criteria to:
-
Ensure developer productivity,
-
Ensure product quality, and
-
Attract a user base.
For instance:
Developers see about a 50% productivity boost when documentation is up-to-date, detailed, reliable, and comes in different formats.-https://octoverse.github.com/2021/creating-documentation/[The 2021 State of the Octoverse, Github]
… Find more stats in the Docs Fact Pack.
What is good documentation?
Good documentation provides:
Just enough info, When it is needed, To support a specific action, At the quality required.
Getting this balance right is both an art and a science. The Good Docs Project explains how, by providing best practice templates and writing instructions for documenting open source software.
Are we there yet?
Not quite. We will be a keystone project when:
-
Open source surveys stop reporting poor documentation as a key developer gripe, and
-
People attribute documentation improvements to The Good Docs Project templates and processes.
Image credits: Keystone image used with permission from Hakai Magazine, How Ecosystems Got a Keystone, Jude Isabella and Adrienne Mason, 2015.
Text of article ©2024 Cameron Shorter
Released under Creative Commons Attribution 4.0 International (CC BY 4.0)