[Ground-station] Documentation Debt

[Michelle Thompson]

Greetings everyone,

If you’ve been in any technical field for any length of time, you probably
know about technical debt.

Technical debt is when you “borrow” against a technical system’s quality.
Teams take short-cuts or use work-arounds, usually to meet a deadline,
instead of doing things like documentation, maintenance, support, and
education.

It takes conscious effort to avoid going into technical debt and it takes
painful and expensive discipline to get out of it. In many cases, technical
debt can bring down a product or project entirely, often without being
identified as the underlying cause.

Out of all of the different types of technical debt, the one most accepted,
and even sometimes bragged about, is documentation debt. On many open
source projects, documentation debt isn’t a bug, it’s a feature. The less
accessible the explanation, the less people will try and put their “dirty
fingers” on a design, and the more control (and credit) the “core
development team” can keep. This is an understandable strategy. Open source
teams aren’t people randomly thrown together, “feature creep” and “good
idea fairies” are toxic, and *not everyone showing up to contribute on your
project is coming with a spirit of goodwill towards the work or the people
doing or using it.* So, making interested people work hard to get involved
can be a filter against weirdos and bullies.

We actively seek the opposite of documentation debt, and largely succeed.
There are plenty of places we can improve, so if you know of one, please
speak up and point it out.

Fridays are “documentation days” for ORI. That doesn’t mean writing stuff
down doesn’t happen on all the other days of the week, However, once a week
all volunteers are explicitly encouraged to send in reports, even if it’s
just a sentence or two, to their leads, on a blog, or to their favorite
board member.

Thank you to everyone out there working on projects at ORI and in the wider
open source communities. We continue to grow and increase activity and
capability.

This increase in activity and capability has lead to a higher than usual
amount of documentation debt. Please take a few minutes this Friday and
share what you’ve accomplished, what you have planned, if you need any
resources to get things done, and if you have any roadblocks you need help
with.

-Michelle Thompson
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openresearch.institute/pipermail/ground-station-openresearch.institute/attachments/20240221/be55d9d4/attachment.htm>