Becoming a Keystone Project
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.
Developers see about a 50% productivity boost when documentation is up-to-date, detailed, reliable, and comes in different formats.—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.
Released under Creative Commons Attribution 4.0 International (CC BY 4.0)