Hacker News Reader

Comment by Hakashiro | Hacker News Reader

Documentation has always been part of the product.

Documentation has always been part of the coding, not an afterthought, not an optional thing, not a second-class citizen. This is how I was taught in university. I'm still baffled to see how many developers believe the key to professional success is writing a lot of computer code, as fast and as efficiently as possible. Then you go to their GitHub repos for their personal projects and they're completely unusable because you don't even get installation instructions. Best case scenario you will get an auto-install script that works on Debian 9 and has been unmaintained for years, but at least you can read what it's doing and adapt it to your distribution of choice.

Complete insanity.

View on HN

I had a classmate who got hit with this issue from the opposite direction. In our first semester CS course, 70% of our grade was based on our documentation. My classmate wrote beautiful, comprehensive documentation of the solution program to each solution set. They also didn't write a single line of code the entire semester, passing the class entirely on the strength of how they documented software that wouldn't even compile.

By the time that they reached the more advanced courses, where producing a working program was a requirement, they were so far behind that continuing in the program was hopeless (e.g. being asked to write a database when they'd never even attempted "Hello, World").

If the department counsellors had been on the ball, my classmate would have made an amazing technical writer, but I believe they wound up switching to electrical engineering.

> I'm still baffled to see how many developers believe the key to professional success is writing a lot of computer code, as fast and as efficiently as possible.

I wonder if developers tend to believe this, or if leadership incentivizes it, either explicitly[1] or implicitly.

1: https://www.platformer.news/p/twitter-braces-for-layoffs

> Rezaei tried to rally the troops, telling engineers to focus on shipping code as quickly as possible:

> "So if you ask what should I do now: do good engineering work. Write code. Fix bugs, keep the site up. I know the criteria for being at Twitter is that. It’s not working on a fancy project for Elon. The good culture change is, it’s shipping and delivering. I encourage you to rotate more on coding and shipping, and less on documentation, planning, strategy etc. If you want to be in a “special” group this week, code and ship 5x as [much as] before. ..."

Probably not insanity, just an omission. It will be gradually improved over time by those people as they mature.

Reply on news.ycombinator.com