Documentation is a necessary skill at senior levels in large orgs. There will never be a shortage of interested parties eager to vampire away your cycles. Being able to send them docs, diagrams, etc. will save you so much oxygen.
Very much so. We're kind of arriving at a workflow which dictates: If one of the experts or architects has to be asked about some topic, the documentation in that area has to be improved, ideally together with that expert and based on their answer. Similar to how an SLA relevant outage requires a post mortem to fix or mitigate root causes.
Not gonna lie, initially this was somewhat annoying. You had to type up long aeswers, or talk about a topic a lot, and then you had to write the same thing down again. So much repetition and so much markdown! So much time not doing tech stuff.
But doing this for a while.. well initially we ran into the problem of having too much documentation and needing to organize it. We enlisted help from technical writers in the company there a bit. But doing this for a while has resulted in very effective documentation for the teams. Not just architectural decisions written from an ivory tower. Very hands-on design guidelines, explanations and how-tos from practical projects in the company. If the ivory-tower-architect yells at you with a direction, those tell you how to get there.
And this generates a lot of velocity and trust in the teams. You have a problem, you pick up the guide, and for seasoned topics, your problem disappears within that sprint with that guide.
Comments
Documentation is a necessary skill at senior levels in large orgs. There will never be a shortage of interested parties eager to vampire away your cycles. Being able to send them docs, diagrams, etc. will save you so much oxygen.
Very much so. We're kind of arriving at a workflow which dictates: If one of the experts or architects has to be asked about some topic, the documentation in that area has to be improved, ideally together with that expert and based on their answer. Similar to how an SLA relevant outage requires a post mortem to fix or mitigate root causes.
Not gonna lie, initially this was somewhat annoying. You had to type up long aeswers, or talk about a topic a lot, and then you had to write the same thing down again. So much repetition and so much markdown! So much time not doing tech stuff.
But doing this for a while.. well initially we ran into the problem of having too much documentation and needing to organize it. We enlisted help from technical writers in the company there a bit. But doing this for a while has resulted in very effective documentation for the teams. Not just architectural decisions written from an ivory tower. Very hands-on design guidelines, explanations and how-tos from practical projects in the company. If the ivory-tower-architect yells at you with a direction, those tell you how to get there.
And this generates a lot of velocity and trust in the teams. You have a problem, you pick up the guide, and for seasoned topics, your problem disappears within that sprint with that guide.