Building an org-culture of documentation

And documentation is more like narration of journey, and not just some annotations of the present state.

Photo by Henry & Co. on Unsplash

As remote/async/hybrid forms of work seem to have settled in and a full in-office atmosphere seems more like past and little like future - one thing that will hurt many companies is underestimating the importance of documentation in org culture.
A thread 🧵👇🏼

To many people in tech "documentation" sounds like ah okay let's annotate our function and classes with some JavaDocs.
No. Documentation is a culture. It is not writing 2 random comments somewhere.
And the best place to learn it is from old and large open source projects.

When you look at garangutan OSS projects like Linux Kernel, Mozilla Firefox, Chrome/Webkit, many of the Apache foundation projects - you truly see what working async means and how the 'documentation culture' is important.
There are some important rules to it

Communication should be public by default, private by exception.
Most communication, even when happening between 2 people, can be of knowledge value to everyone in the org. Promote talking in Slack channels over DMs.
Promote open channels over private channels.

Documentation is not just about the present, but about the past and the future. This is something 99.99% people don't get
I had learnt so much about "why" the current stage a project is in, but reading through hordes of old Confluence pages and rewinding the git clock on README

If there isn't a knowledge base that covers mistakes made, documents past events and their RCAs - newer members of the teams are bound to repeat them.
Tech (and non tech) teams are like ships of thesus. Often 4-5 years later every member of the team has changed.

There is often a lot of emphasis on asking 5 why's and creating detailed RCAs after a production fault.
I can stick my neck out to say 9/10 orgs that have very detailed RCA processes, still do not encourage+facilitate new team members to read historical RCAs.

Much like how a lot of people in STEM speak out of their ass about geo-politcal, and social issues because they never studied history properly, most tech teams do a lot of avoidable things on a day-to-day basis which is avoidable if they knew their own history.

Now apart from past, documenting the future is very important
Something I like to keep telling people when planning products is - we always must have a 1 year and a 5 year plan
Standing in 2020, my goal for 2021 might be very different than what I thought I'll do by '21 in 2016

But it was important that in 2016 too, I had a goal for 2021 in mind. Both your 1 year and 5 year plans keep evolving. Sometimes they can pivot 180°, but they must exist.
Without "vision", whatever remains, is always "chaos".

I have often joined orgs, or gotten pulled in to advice orgs, where I have had to work my way through waaaaaaayyy too many 1-on-1s with lots of different people to piece together "wtf are we all even doing here?"
This is a recipe for disaster, especially in async/remote setups.

You cannot bank upon someone up top to always get in 1:1s with new people to give a download of "what are we trying to do here"
They should just rather write some long-form articles describing their vision and make it part of the documentation of the org, simple.

Good, talented, smart people are curious by nature. Give them a knowledge base with history and vision. Give them a manual of the current state.
See how fast they self-onboard, see how quickly they align themselves to what you're trying to achieve without repeating past mistakes

I understand that none of this is easy. If writing things down doesn't come naturally to you, and "let's get on a quick call and I'll explain" is your knee jerk reaction usually, you'll have to take conscious steps towards this. It will be a slow and deliberate journey.

But trust me - the end results will leave you overjoyed. If you're in senior leadership, or you're a founder or heading vertical - this is squarely your job to do.
In fact, this is your ONLY job to do. Just do this, and hire people to do everything else.

Narrate a story, paint a vision. Step back and let people take charge and achieve it.
/end