5 ms·

Good article. > Few developers like to write documentation. That means it’s your job. OMFG. Most traditionally-trained devs I've met in person are next to ill

Good article. > Few developers like to write documentation. That means it’s your job. OMFG. Most traditionally-trained devs I've met in person are next to illiterate. Bizarrely incompetent at docs. Unsurprisingly their code quality stinks too. They'd probably ridicule you for mentioning "programs must be written for people to read, and only incidentally for machines to execute". (Unless you say you're quoting "the Wizard Book", because they defer to argument from authority.) Read my sourcecode, they say, as if that doesn't mean "Go fuck yourself". And they simply never want to proactively improve. That would require introspection and self-critique. Pulling teeth.

vinceguidry 11y ago
You have to work within people's limitations, that is, if you can't pick the people you work with. A team is only as good as it's most competent member's willingness to pull everything together and inspire the less-motivated to perform at a higher level. That's leadership, and there's precious little of it anywhere, even (especially!) in the products we use every day. If there's no real leadership, then you're stuck in the backwaters of being managed. My advice is if you find yourself in this situation, either use it as an opportunity to work on your leadership skills or check out and throw your passion into side projects.
- calibraxis 11y ago
  Excellent points! Maybe anyone who decides to "check out" should consider getting physically away from the team, if possible. Find those who proactively help others and apply healthy self-critical thinking. Kathy Sierra in "Badass: Making Users Awesome" said: "An important, unconscious way to develop expertise is being around high-quality, high-quantity examples of expertise." The flipside is apparently true: exposure to mediocre examples begets mediocrity.
dlitz 11y ago
No kidding. I don't know how many time I've tweaked my code after starting to write some docs (docstrings/JavaDoc/etc.) and realizing that my abstraction boundaries were wrong. If writing those docs were somebody else's problem, my code would have been crap. This is after 10+ years in industry. On the other hand, end-user documentation can be a lot of really tedious screenshotting in some markets, and it can't always be automated.

vinceguidry 11y ago

You have to work within people's limitations, that is, if you can't pick the people you work with. A team is only as good as it's most competent member's willingness to pull everything together and inspire the less-motivated to perform at a higher level. That's leadership, and there's precious little of it anywhere, even (especially!) in the products we use every day. If there's no real leadership, then you're stuck in the backwaters of being managed. My advice is if you find yourself in this situation, either use it as an opportunity to work on your leadership skills or check out and throw your passion into side projects.

calibraxis 11y ago
Excellent points! Maybe anyone who decides to "check out" should consider getting physically away from the team, if possible. Find those who proactively help others and apply healthy self-critical thinking. Kathy Sierra in "Badass: Making Users Awesome" said: "An important, unconscious way to develop expertise is being around high-quality, high-quantity examples of expertise." The flipside is apparently true: exposure to mediocre examples begets mediocrity.

dlitz 11y ago

No kidding. I don't know how many time I've tweaked my code after starting to write some docs (docstrings/JavaDoc/etc.) and realizing that my abstraction boundaries were wrong. If writing those docs were somebody else's problem, my code would have been crap. This is after 10+ years in industry. On the other hand, end-user documentation can be a lot of really tedious screenshotting in some markets, and it can't always be automated.