Is there something I'm missing about documentation? My PMs seem to think it's something I don't want to do without knowing me at all.
For background, I've been a dev for 5 years, and within the past 6 months, have transitioned to a solution architect.
For my entire career, I've been stressing the need for documentation, proper planning and testing, basically time to do things right.
The company I'm at is very fast paced. My team has not (until very recently with the change of management) had time to actually do any of the proper work. We basically had our entire operations systems fueled by tech debt, to the point where I became convinced this was just a strategy.
Now that I'm more heavily involved in planning and working out the details of larger projects, I have PMs asking me to document things, and stressing to me in a teaching tone the importance of it.
We're still in a fairly big rush after launching a massive overhaul, and I still need to do a ton of support work, along with working out details for many many projects that keep coming up. I have more time, but still not enough time unless I really manage my time perfectly (even then, it's difficult and my support has been dwindling).
When I'm asked to come up with documentation to explain ideas and concepts, I explain that I have not had time to get to it yet, but that it's on my list of things to do as I free up a bit.
Any time I mention this, the response is usually some kind of "Yes, I know it's not a fun thing to do, but its important", which always gets on my nerves because I've been the one complaining about the need for so long.
I literally do not have time! I want to do the documentation more than anything. I want to make sure everyone understands and can appropriately do their own work with the information. If I relax for 5 seconds I get yelled at for not answering support tickets, or for not responding to questions.
To be thought of as just being lazy and not doing the "boring" work is a massive slap to the face. Is this a common thing? Is there something I'm missing about how I should be going about this position?
Posted Feb 5, 2020, 12:15 AM UTC
I was in a similar position. I’m the unofficial “special ops” guy. I officially belong to a team as an IC just to track my work, but unofficially, I’m the one person that gets pegged with no clear requirements, just a high level system request and I’m suppose to get it done.
What ended up happening was that I had new work to do and because I was the only person who knew how the projects I had worked on worked, I was always dragged in to explain them or add new features.
At one point after getting a few wins, I can just point blank say, “today I’m working on documentation. No it’s not on the board and it’s not part of the project plan”. Now when a request comes up to change anything, I can point people to documentation. I also make sure that the CI/CD pipeline is created.
You have to speak truth to power. Push back and demand time to document before you start on a project and/or after you have completed a project.
This IC concept is new to me, I didn't know this was a standard thing. I actually brought this up very recently as a possibility without knowing, as it made sense to me to be completely on my own as my work affects many teams and I need to talk to everyone across the business anyways.
If that goes through, I think I'll be able to push back more effectively. I suppose I just need to grin and bear it a little while longer, continue making some progress, and give myself enough room (and wins!) to be able to completely focus on this.
The good thing about being here is that theres no shortage of opportunities for as long as my heart decides to keep pumping under stress.
The sort of management focus you describe in your op is indicative of shortsighted recklessness that results from a lack of investment in subordinates quality of life. It seems likely to me that they expect you to dedicate your personal time to writing docs.
In my now 11 year career I've had 2 coworkers pass away unexpectedly. One was the Linux Admin overseeing the hardware on which all 800 of my databases were hosted. The other was the techarch I was reporting to while his junior in the effort to develop an analytics backend for a smart grid metering pilot program.
In both cases I inherited the empty role. My late Linux Admin was a prolific documenter and it saved me my mental and emotional wellbeing. The other guy documented nothing and ultimately, although we delivered, it was at the cost of some 4 months of contract extension and my sleep for that entire duration.
That first one taught me a lesson, the second I learned it. Documentation is on the same level of importance as backups. But for managers or product owners who've never experienced any sort of serious personnel loss among their technical experts, it just doesn't occur to them that the knowledge has a legitimate chance of suddenly disappearing.
This made me think of a much less tragic reason for documentation. It’s impossible to move on to the new shiny at the same company if you don’t document your work where someone else can take over. Your only recourse to getting out of the trap is leaving the company.
Right and it's also hella satisfying to reply 'RTFM' when you encounter somebody who tries to abuse your time asking for KT without investing themselves in the learning.
At this point I enjoy writing markdown like a sick freak.
I disagree with posters saying they want you to overextend yourself or do this in your spare time. They probably don't understand your workload and think since you don't write docs you don't want to.
They're asking you to prioritize docs higher than other work you are doing.
As the poster above me says, call their bluff, basically. Find an important doc that needs to be written (you can tell by how many times you have to help someone do a task that could be documented). Make a time to write that doc. Don't wait for there to be zero tickets waiting for you - write a ticket, mark it high priority, and do a great damn job. Make time, don't find it. Ignore slack and email and your other tickets as much as possible until it's done.
Then notify potential users of the doc what you have written and how to find it, and give it to others who might need to share it around as well. Show the docs to your PM's.
When they ask why you aren't keeping the same pace on your technical work, explain that you heard them saying how important docs are, you agree with it, and decided to prioritize it higher than you were before, which means not doing whatever else it was you were going to do.
Now they know a) you can write great, useful docs they want, b) you agree with them on the importance of docs, c) you weren't being lazy, you were just prioritizing other asks for them. If they're smart they will start to realize if they want docs, they just need to make it as high priority as the other things they are asking for. A slight shift in attitude and assumptions from them is all that's needed.