The Power of Documentation Seen Through the Lens of a Manager

Problem

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.

Actions taken

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.

Lessons learned

• 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.