How can I work better with a manager who is stubborn with documentation
My manager is putting lot of emphasis on documentation .
It consumes lots of time to document almost everything and its equally challenging to keep it updated as well. For example, if we are doing some dev work or exploring a new tool , we are expected to document everything step by step. (I am ok with creating regular design docs, onboarding docs etc).
I believe one has to find a sweet spot (or strike right balance between actual dev work and documentation ) . Any tips on how to deal with this ?
Discussion
(2 comments)- 36 months agoEntry-Level Software Engineer [SDE 1] at Amazon
In my experience, there are a few situations where up-to-date documentation makes sense. For example
- Onboarding new engineers to the team
- Oncall runbook on how to diagnose/fix/rollback common issues
- Onboarding team members to a new service, how can a team member compile/start/run the code and start tinkering? What are the coding standards/guidelines for that repository, etc
- User guide on how to use the product you are developing (this documentation is for the customers but engineers should contribute to this too)
- Design docs on how the architecture of the service works at a high level
- Documentation that roughly outlines the stakeholders (upstream and downstream dependencies, etc)
Quality over quantity is crucial in documentation, as it tends to become outdated. Ask yourself if the documentation you are writing falls into any of the categories above. If so, is the documentation at a sweet spot in terms of depth? I often find that documentation that's too specific cannot be understood by many and documentation that's too generic is not helpful.
I once worked at a consultancy where we had to document every hour of our work to show clients how their money was spent. Try to avoid working with such companies if possible.
- 16 months agoEng @ Taro
I would try to grade each type of documentation along how much time will each doc save versus the amount of time it will take to write and maintain each doc. It's easy to underestimate how docs can also lead to confusion if they get outdated.
For example, if there's an onboarding doc that every new engineer will use, and it saves them each 15-20 minutes, it's probably worth creating the doc.
For dev work, most documentation is captured within the code, PR description, or task, so it's probably not worth doing any additional documentation
For exploring a new tool, it can depend. If it's how to use the tool, people can usually refer to that tool's docs. But, I could see a case where it might be worth it to outline the tradeoffs of a new tool versus other tools so other people can understand the history of why a tool was selected.
