Wednesday 24 May 2023

Keystone Project - The Good Docs 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.

For instance:

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:

No comments: