Better documentation and knowledge sharing creates transparency that aids onboarding, prevents turnover disruption, and withstands reorganizations. Different practices can help, such as communicating asynchronously, creating incentives for documentation, making docs discoverable, understanding team members’ preferences, and providing dedicated writing time. And maybe InnerSource can help too.
Picture this; you’re new to a company, and trying to learn about the internal shared infrastructure platform. After searching the internal documentation site, you don’t find your answer, so you head to an internal messaging tool, like Slack, to ask for help.
Through Slack, you find the answer to your question from another engineer but discover that the information is not written down anywhere. This is not an ideal method of finding your answer, but it is very common. You’ll get an answer to the question, but what happens the next time someone asks the same question? This issue is prevalent with documentation, diagrams, architecture decisions and other modes of understanding why systems work the way they do.
Improving documentation practices can help build organizational resilience by making information more transparent and accessible. In my talk at QCon San Francisco 2023, I discussed the challenges of good documentation, as well as a few solutions.
Poor documentation can affect organizational resilience in a handful of situations:
Turnover – There can be a disruption in continuity when someone leaves the company if only a single person knows how a system works.
Onboarding challenges – In some companies, the burden of improving documentation falls on new staff. «Go through our documentation and tell us what’s missing» isn’t a very welcoming introduction.
Re-orgs — People get moved around. Teams get moved around. Most of the time, the systems that they supported in a previous role get carried around with them. They have this baggage of support, even though they’re on a new team and supposed to be building something new.
Outages – If you must call someone in the middle of the night to find out how a system works, or find the right dashboard, your outage is going to last longer. And it’s a burden to have to call someone in the middle of the night. What if they’re on vacation? What makes good documentation?
Documentation by itself doesn’t necessarily solve all the challenges of useful and discoverable information. Bad or overly verbose documentation can cause more problems than it solves. When writing documentation, ensure that it is:
Useful
Relevant
Correct and up-to-date
Discoverable Documentation Challenge Solutions
There are a handful of adjustments you can make within your team or engineering organization to improve documentation, increasing resilience at the same time.Communicate asynchronously
Take the time to think through and write down your problems before you introduce them to people. This will help you get better at communicating asynchronously.
I came across Kidlin’s Law recently:
«If you can write the problem down clearly, then the issue is half solved.»
It’s like rubber ducking in programming. I’ve seen this happen during important conversations I’ve had with colleagues, where we want to make some big technical decision and they haven’t fully formed their thoughts around how they want to solve it. They will propose a major change in a meeting, but they haven’t figured out why they want this major change – maybe they just read a blog post about using this particular tool to solve a problem. The people in the meeting will identify reasons not to make the change, and then the engineer will feel discouraged and back away from it.
I encourage people to take a day or two, and write down what the problem space is, and what the proposed solution is, and then share it with people. Let others have time to digest it, and comment asynchronously. This allows for more thoughtful solutions.Teach and encourage writing culture
Google and other places have technical writing courses available. These can be very helpful to ensure your organization covers the basics of technical writing. This includes writing in an active voice, using correct grammar, and being informative, but not overly verbose.
