The Power of Documentation Seen Through the Lens of a Manager
2 August, 2020
Comprehensive, reliable, and accessible documentation is a must as it helps managers ensure consistency and alignment across the company. However, many companies lack a consistent documentation method that, among other things, further complicates the onboarding of new engineers and getting them to understand what their role is. I particularly find it hugely empowering the ability to define through documentation the scope of an engineer’s role and thus provide them with the framework within which they could contribute to the best of their abilities.
As in other things I like to set standards by leading by example. As a technical person who is more off the tools and managing, being able to document architecture cements my understanding of it and allows me to critique it without sliding into micromanaging.
Also, I try and give engineers and architects the tooling and frameworks they need to document and then collaborate with them on a few key journeys through the stack or platform and show them how it works all the way through. It then empowers them to contribute and feel they have ownership over that documentation.
I generally create a number of templates to make the barrier of entry to creating written documentation even lower, this may include How-To’s, Testing Plans, Architecture Overviews, Architecture Decision Records and Incident Reports. If your tooling allows, demonstrating the workflow that engineers can use to generate visual documentation that doesn’t require exporting and updating on every change can be a game-changer and really get people bought into the value of it.
I also read much of that documentation daily and did so at different companies throughout my career, commenting and re-affirming the importance of the documentation and the time people have taken to create it. In all those different places, documentation has been presented differently but what really matters is that it is a living thing, that anyone can contribute to and make better, not something static that becomes obsolete and unneeded.
- Documentation is difficult for many reasons and different people learn and process information in different ways. Some are more visual types, some prefer written documentation. But, don't get too hung up on that; write and share, and use tools that encourage team collaboration. I sway towards tools that don’t have per head user licenses and that encourage more people to get on board.
- A framework for documentation provides engineers to grow in their careers more successfully, providing the opportunity to release them of daily duties and transfer knowledge of otherwise unknown areas of technical work to their colleagues, other teams and new starters.
Scale your coaching effort for your engineering and product teams
Develop yourself to become a stronger engineering / product leader
Vadim Antonov, Engineering Manager at Meta, dictates how he brought a brand new team into the remote learning process by ramping up onboarding and creating a mentor system.
Engineering Manager at Facebook
William Bajzek, Director of Engineering at Sapphire Digital, compares and contrasts a team structure that utilized siloed skill sets and one where everybody’s duties overlap at the edges.
Director of Engineering at Sapphire Digital
Neelima Annam, Sr Director Information Technology at Outmatch, shares how something as minor as collaboration tools can be a BIG issue during mergers and acquisitions.
Sr. Director Information Technology at Outmatch HCM
James Engelbert, Head of Product at BT, shares how managing up is all about being an excellent manager to bring the best out of a team.
Head of Product at BT
Piyush Dubey, Senior Software Engineer at Microsoft, shares his journey of climbing up the career ladder through awkward times dealing with an introverted manager.
Senior Software Engineer at Microsoft
You're a great engineer.
Become a great engineering leader.
Plato (platohq.com) is the world's biggest mentorship platform for engineering managers & product managers. We've curated a community of mentors who are the tech industry's best engineering & product leaders from companies like Facebook, Lyft, Slack, Airbnb, Gusto, and more.