The unintended consequences of trying to do it all
On my first job as a manager at Microsoft, the software developers on my team were spending too much time documenting code. They were writing architectural documents, design docs (design docs for devs are not about graphic design but code design), diagrams, and even going back to the code and adding comments.
A little documentation of how a component or service works is always useful, but when a dev has to add a 30% cost estimate to each feature to account for documenting it, I started to get worried.
(Sidebar: I was mostly worried about the time spent, but also by the time wasted. The more documentation you write about an implementation of a feature/component the more likely it’ll be outdated in a short period. The code is alive, and the documentation only reflects a snapshot in time. Documentation that is outdated is knowledge tumor.)
That important thing about a {developer}
I retreated and thought why that bothered me. Why writing good and high-quality code documentation wasn’t where I wanted my team to spend their time? In the many pivots of this problem in my head, I arrived at one that made the most sense to me. A year from now, when I look back to hand out promotions, all other things being equal, would I give a promotion to the software engineer who developed fewer but well-documented features, or to the developer who produced more features, but had poor documentation. The answer for me was clear.
The important thing about a developer is that they write code(1) to solve problems.
This post is not about software engineers. It’s about any professional with any title. Replace it with the VP of HR, business analyst, technical writer, graphic designer, CEO, project manager, or any other role, and you’ll have an analog for each of those. Each position has their primary purpose. Their raison d’etre (I just spent most of my French). It might have other responsibilities, but all are secondary to the main one, which defines the role.
Praises that backfire
Why were the developers spending too much time on documentation instead of building features? The answer is operant conditioning, more specifically, positive reinforcement. The people that work the closest with software engineers (besides other software engineers) are PMs (Product/Program/Project managers) and testers.
PMs, testers, and other devs tend to appreciate when a feature is well documented and how the implementation works. It helps them comprehend it, it makes their job smoother, and they need fewer back-and-forths between them and the dev owner to know what it does, how it does it, and what it could do. In turn, the better the documentation of implementation is, both in clarity and depth, the more likely they are to praise the developer who wrote the documentation.
Here lies the trap.
Often, a developer won’t get many praises for the code work they did because “that’s their job.” However, they will get acknowledgment, praises, and sometimes even rewarded(2) when they go “above and beyond.” The more they do the extra work, the more praises, the more they feel good about it.
Given enough months (or years), a person might end up off-track from their primary reason to be there. They might not understand where things went wrong in their career when they don’t get promoted, become slow to do their job or just feel the people at the same level are getting the “good features” while they are not.
(Again, this is not particular to software engineers. All professionals can fall into this trap.)
In a way, it wasn’t the person’s fault. It was everyone around them giving mixed feedback signals of what it meant to be great at that role.
Some people are immune to this. I’ve seen people who have immense clarity on their role inside of the organization and can keep the focus on what they need to do. Sometimes they are seen as not helpful or isolated, but they do (well) the job they need to do, and they know how to say no or ignore the secondary tasks to guarantee exceptionalism at the primary.
Been there, done that
I can go back to my career many times and realize how I was misguided on what I should be doing. I got (was) distracted. This problem compounds when you work at a startup because there are so many things to do and so many hats to wear.
Even if you wear three hats, you’ll have to split your time between these three primary reasons, and until all of them are done well, with speed and efficiency, secondary tasks should be left to rot or only cross the bar of minimum acceptable to unblock a coworker or project.
Here is a management book for you to read on the topic(3):
(1) That’s an oversimplification. Software engineers do a lot more than write code to get features done. However, if there is no code, they wouldn’t be called software engineers.
(2) Being rewarded in this context is short-lived and typically a one-off. If you are being recognized and rewarded by secondary tasks, you should be worried about your career, and you should have a conversation with your manager about it.
(3) It’s recommended to me by my colleague Matthew Matanovic.
