View profile

Level Up - Issue #138


Level Up

April 3 · Issue #138 · View online

Level Up delivers a curated newsletter for leaders in tech. A project by Ideal for busy people such as Tech Leads, Engineering Managers, VPs of Engineering, CTOs and more.

Improving team and organisation documentation
I had a great question this week about how to avoid team and organisation documentation being outdated and useless. When I hear this, I often respond with, “What mechanisms do they have in place to keep documentation valuable?”
Documentation is a classic tragedy of the commons problem. Most organisations hope individuals will keep documentation up to date and relevant but when leaders incentivise and reward individual work (i.e. finishing stories, code, etc) over long-term or team-beneficial work they don’t realise they are setting up a system for failure. Most teams need a counterbalancing force to encourage documenting important information and keeping existing documentation up to date. It’s the leader’s responsibility to ensure there is enough counterbalancing force.
Most people don’t realise that documentation is a people problem. People problems don’t get solved with tools despite many leaders in tech asking, “What tool does your organisation use for good documentation?” Here are some ideas that work for organisations that maintain great documentation:
  • Identify a librarian - Great documentation isn’t about capturing information, but about making captured information accessible. There’s a reason that Wikipedia has a set of editors to make sure that content is not only relevant but also discoverable. Librarians don’t have to be a full-time role or position (sometimes they are), but someone needs to guide information so that others can easily contribute to the existing structure and help people find it.
  • Recognise documentation as part of daily work - If you think documentation is valuable, any “definition of done” should include the time it takes to add to or update existing documentation. This means teams should plan/estimate time to update documentation and a piece of work is not “complete” until the relevant documentation is captured.
  • Regularly test for usefulness - The value (or correctness) of documentation is sometimes hard to test because its value is realised at a different time than when it was produced. Since you can’t always “prove for usefulness” as soon as documentation is written, think about regular reviews to see if existing documentation provides valuable detail. A good test is when someone new is starting as fresh eyes provide different insights. If not, use a quarterly or at least once a year review to see what documentation is out of date, no longer relevant or what is missing.
  • Make it easy for people to contribute - Documentation will never get updated if someone has to raise three tickets and spend a week chasing approval to get a small change. Agree and publish on a structure about what information should go where. Make it easy for people to suggest improvements or even make the changes directly (tools that provide revision control make it easy to revert where necessary). Don’t put lengthy approval processes on everything (just the high risk or sensitive areas such as legally-binding policies)
Although no documentation is ever perfect (like software, it should keep evolving), it doesn’t take too much effort to transform zero/poor documentation into useful documentation. The state of documentation reflects the culture and expectations you set as leaders. Remember that culture is not just the behaviour you allow, but also that which you tolerate.
Your challenge this week is to look at what you do encourage and improve documentation? What counterbalancing processes do you have against the constant and endless flow of individual work?
Enjoy this week’s newsletter, please pass it on to a friend or colleague who might benefit.
Join an online guided course, Shortcut to Tech Leadership (IC track) or Engineering Manager Essentials (Management track) to level up your skills. Or grow your value as a technical leader with self-paced courses at the

It's no accident books are easy to find in a library.
It's no accident books are easy to find in a library.
Sponsored Content
Last chance to register for INTERACT
Just 3 days left to join the new faces of engineering leadership plus leaders from Stack Overflow, Netflix, Slack, Netlify, and more at INTERACT on April 7th for a free virtual event!
How Engineering Managers Fail
Margaret Hamilton Recalls Her Life as a Programming Pioneer
Changing jobs during the Great Resignation
On offering help that’s actually helpful
Technology Radar Edition #26 Published
Mozilla’s vision for the evolution of the Web (Executive Summary)
C Isn't A Programming Language Anymore
Learn to manage systems, not people with this introduction course to Systems Thinking
Learn to manage systems, not people with this introduction course to Systems Thinking
Organisation & Processes
ZEN and the art of Reliability
Why you should work asynchronously
Local industry lobby says IT pros fleeing Russia
Tweets of the Week
Expand this thread to learn about 8 principles that are super useful to remember in a remote work context. 👇👏
Marissa Goldberg
I've helped dozens of companies switch to an async-first work environment. This means fewer meetings and more quality work done.

When companies switch to async wrong, it slows their work. I created the Work Forward Approach to prevent this.

Here are the 8 core principles ⬇️
Some great advice 👇
estherderby 🌻
Rather than stick ppl who are between teams or project on some radome team to keep them busy, let them work on their own special projects, do self-study, attend training, or just take a breather. #AvoidTeamChurn
Thanks for making it this far! 🤗
If you enjoyed this newsletter, send me feedback and share it with others!
Want to level up your technical leadership skills? Sign up for online interactive courses like Engineering Manager Essentials or Shortcut to Tech Leadership or check out self-paced courses at the Tech Lead Academy.
Did you enjoy this issue?
In order to unsubscribe, click here.
If you were forwarded this newsletter and you like it, you can subscribe here.
Powered by Revue
Patrick Kua, Postfach 58 04 40, 10314, Berlin, Germany