Profile picture
Mike Cvet @mikecvet
, 20 tweets, 4 min read Read on Twitter
If you're a member of a large, complex, or highly tribal software engineering organization, then this thread is for you.

Let's talk a little about living technical documentation for software systems.

There's a broad set of classes of technical documentation which we could cover, but I want to focus on higher-level descriptions of complex systems or their components.
Also important, but maybe covered later, is technical design documents and proposals, or code internal documentation.

This could be anything from a runbook, to a description of a service's request rate-limiting semantics, to a description of the client-side translation of server responses, to a description of the technical underpinnings of a major product.
Why spend time writing these documents? Aside from the obvious self-serving reasons for you as a person, there's a few things that benefit your team and your larger organization.
Continuity: Teams change - they lose members, onboard people, shift focus.

Our organizations are always in flux.

We have a responsibility to both bring new members up to speed quickly /and/ preserve the mental context of those moving on, for the benefit of others.
Without written documentation, we're all just playing a giant game of telephone, describing highly complex systems with many moving parts, and getting it slightly wrong every time.
Efficiency: Docs defend time.

If multiple people can consult ground truth documentation for how something works, they're not asking other, more experienced teammates, for the same information over and over again - each time getting a slightly different story.
See game of telephone, above.
History: Describing the circumstances which motivated a project, and surfacing how components could be improved or deprecated to others.

This often helps the reduce the operational burden, as well as the breadth of context, required for members of your team.
Image: A healthy team documentation culture makes your team appear to be domain experts on your responsibilities.

It also makes the team appear to care about their work, and that it incentivizes and rewards learning, and paying down technical debt.
Make no mistake - documentation debt is technical debt.

If your team's work portfolio doesn't consider writing or fixing technical documentation relevant to its balance of technical debt, your backlog is leaky.
All this to say: make the team seem like a great place to work.
Some tips and rules of thumb:
Know your audience: A single document (or author) shouldn't attempt to serve everything for everyone.

Are you writing for the team?

These could be onboarding docs, reference materials, localized technical design docs.
For people outside the team with familiarity with the team focus:

Engineers (or others) with suggestions for improvement, owners of dependent systems investigating incidents, owners of dependency systems trying to familiarize with customer use cases.
For people further outside the team:

Curious employees, people considering transfers into the team, authors of new designs researching prior art.
Make docs discoverable so that people can find them.

And preemptively write accessible documentation for things you know the team will get asked about.
Encouraging (and assisting) junior team members to write the technical documentation is an excellent way to both help them gain familiarity with new aspects of the system, as well as an excellent mentorship opportunity for the senior team members.

Also: fresh eyes find bugs
Anyways that's it for now. Happy writing!
Missing some Tweet in this thread?
You can try to force a refresh.

Like this thread? Get email updates or save it to PDF!

Subscribe to Mike Cvet
Profile picture

Get real-time email alerts when new unrolls are available from this author!

This content may be removed anytime!

Twitter may remove this content at anytime, convert it as a PDF, save and print for later use!

Try unrolling a thread yourself!

how to unroll video

1) Follow Thread Reader App on Twitter so you can easily mention us!

2) Go to a Twitter thread (series of Tweets by the same owner) and mention us with a keyword "unroll" @threadreaderapp unroll

You can practice here first or read more on our help page!

Did Thread Reader help you today?

Support us! We are indie developers!

This site is made by just three indie developers on a laptop doing marketing, support and development! Read more about the story.

Become a Premium Member and get exclusive features!

Premium member ($3.00/month or $30.00/year)

Too expensive? Make a small donation by buying us coffee ($5) or help with server cost ($10)

Donate via Paypal Become our Patreon

Thank you for your support!