Hacker News Reader

Comment by klenwell | Hacker News Reader

Ha. I can relate.

At my last gig, it wasn't the seniors developers (well, it was some of them, too). It was the principal developer.

As my supervisor, he told me, a senior developer, I asked too many questions.

"A senior developer shouldn't need to ask questions."

My questions usually weren't even technical questions but rather questions meant to clarify business specs so that we could make better technical decisions.

At my last performance review, when he dinged me for lacking knowledge expected of me in my role (one of the boxes in the evaluation form), I pointed out I was the one who had done most the documentation for our major applications.

His response:

"A senior developer shouldn't need documentation. The knowledge should be in your head."

View on HN

> "A senior developer shouldn't need documentation. The knowledge should be in your head."

What?! This guy isn't fit to be principal developer.

Sure, the knowledge should be in your head, but it should also be documented in case you get hit by a bus or go on vacation.

Does no one senior ever stop to think about business continuity? What happens when you onboard someone new? A senior developer is just supposed to drop all their work and get the new person up to speed for a month?

I find that companies with a bad documentation culture see it as a cost center ("this takes so much time") whereas companies with good documentation culture realize that even if it takes time, the benefits far outweigh the costs.

Completely agree. On a side note, the one answer that I always get from management when I suggest that we should write more documentation is: "Well, writing documentation could be useful but maintaining it is hard. So I don't think it's a good idea".

As you said, this should be part of the culture. Documentation should be seen as an artifact that is equally as important as the software deliverable itself.

> "Well, writing documentation could be useful but maintaining it is hard. So I don't think it's a good idea"

Your management does not understand the value of good documentation.

Flip the industry:

"Well, airplanes are useful for transportation, but maintaining the documentation takes too much time. So we should skip writing the maintenance documentation and just let the mechanics figure it out themselves every time they need to replace a part" (assuming the plane doesn't fall apart mid-flight)

If you framed it as such, they would see that their counter-argument against documentation is silly. Now, they could argue that your software isn't life critical and people won't die if it fails, but personally I think that's beside the point. It's a business decision the aviation industry has made to document things thoroughly and it's paid off in spades for them.

Of course you have to invest time and effort into documentation, but you maintain it the same way you maintain your software or your tests.

It sounds like your management doesn't realize that although documentation has a visible cost (people's time) it also has many invisible savings: to quickly reference in emergency situations, employee illness/vacation/departure/onboarding, supporting legacy versions.

tl;dr - your management sees documentation as a cost center

Explaining Bus Factor can be helpful in getting their attention. "Sure, documentation is a cost center. You know what's a bigger cost center? Not having it."

https://en.wikipedia.org/wiki/Bus_factor

> "A senior developer shouldn't need documentation. The knowledge should be in your head."

So a senior developer shouldn't document, and shouldn't answer questions (since he said one shouldn't ask questions)?

What's a junior dev to do when there is no documentation and no one to ask for help/clarification?

Why, look at the senior developer's brilliant, perfectly intuitive code, and know everything about the system instantly, of course!

I live this life right now. No documentation, and the senior devs have left, so you just have to figure out what the hell they're thinking as best as you can with the code left behind, sometimes stepping through everything multiple times to see how the data flows through it. Thankfully one of the architects that used to work here knew how to make readable, modular code, so our newer projects aren't too bad to modify, but our legacy systems are awful nests of spaghetti.

Reply on news.ycombinator.com