3 ms·

This is harsh, but I largely agree. I think the issue is that you often weren't hired to write docs either... biz often only cares about new features. It's not

by __jem 5y ago

This is harsh, but I largely agree. I think the issue is that you often weren't hired to write docs either... biz often only cares about new features. It's not the writing docs is hard, but that it takes a lot of time. I can write great docs, but it easily takes 50% of my time relative to code. The quality falls off pretty hard too -- my half-effort docs are pretty bad, like maybe worthless? Obviously, there's a baseline level of, like, just commenting code which some devs still complain about, and that's absurd. But I think we need to be better at getting other people to value docs if we want them to be written, because they take time and effort to produce, it's a tradeoff like anything else in building software.

pdimitar 5y ago
IMO the only way to achieve that is to inform the business about it. If they are aware that knowledge is being lost and then has to be re-acquired by the next person then I think that a lot of business people immediately grok the idea that not writing docs is a liability and a risk and that it makes swapping people hugely expensive (indirectly, due to you being paid just to catch up for a while). Businessmen get this stuff quite well. But I feel very often nobody explains them the situation.
- __jem 5y ago
  Yeah, I agree that business people are often quite receptive when you lay it out in terms of economic impact. I agree that this is a skill all devs should work on -- even just being able to talk about orders of magnitude of $ in your estimates is incredibly helpful. But I've often found other devs can be your worst enemy here -- they rely on esoteric knowledge to build defensible moats around their seniority. Harder to convince execs about firing their "star" 10xer. Ultimately, this is why I think we need compiler assistance so that stuff like docs can be enforced in CI unilaterally.
  - pdimitar 5y ago
    > they rely on esoteric knowledge to build defensible moats around their seniority Sadly you are correct. Job security and thus gatekeeping are the higher priority. So yeah, yet another case of perverse incentives. :( > Ultimately, this is why I think we need compiler assistance so that stuff like docs can be enforced in CI unilaterally. Completely agreed, plus declarative programming. At 41 I am already sick to my stomach about having to manually write boilerplate. Tooling helps only a little and is hugely overrated; so what if the tool generates skeleton controllers et. al.? 90% of what you know should be there is yours to do anyway. But that's a huge tangent. :)
loopz 5y ago
I read docs from 10 years ago, still relevant, but just hard to get any value out of. You can see they try to tick all the boxes, but there's very little practical value, direction or any insight. They don't communicate or provide entry steps into a domain, just list stuff very structurally. So much labour seems to have gone into making too much structure vacant of content, following invisible guidelines while trying to please uncaring taskmasters, long gone. I think we're going to go down a more personal road, start caring about who reads what, and just write what would help out, initially, and as reference. Lots of projects on Github do this right, the popular ones, as they convey meaning much better than their competitors. Such examples stand the test of time too.

by __jem 5y ago

pdimitar 5y ago

IMO the only way to achieve that is to inform the business about it. If they are aware that knowledge is being lost and then has to be re-acquired by the next person then I think that a lot of business people immediately grok the idea that not writing docs is a liability and a risk and that it makes swapping people hugely expensive (indirectly, due to you being paid just to catch up for a while). Businessmen get this stuff quite well. But I feel very often nobody explains them the situation.

__jem 5y ago
Yeah, I agree that business people are often quite receptive when you lay it out in terms of economic impact. I agree that this is a skill all devs should work on -- even just being able to talk about orders of magnitude of $ in your estimates is incredibly helpful. But I've often found other devs can be your worst enemy here -- they rely on esoteric knowledge to build defensible moats around their seniority. Harder to convince execs about firing their "star" 10xer. Ultimately, this is why I think we need compiler assistance so that stuff like docs can be enforced in CI unilaterally.
- pdimitar 5y ago
  > they rely on esoteric knowledge to build defensible moats around their seniority Sadly you are correct. Job security and thus gatekeeping are the higher priority. So yeah, yet another case of perverse incentives. :( > Ultimately, this is why I think we need compiler assistance so that stuff like docs can be enforced in CI unilaterally. Completely agreed, plus declarative programming. At 41 I am already sick to my stomach about having to manually write boilerplate. Tooling helps only a little and is hugely overrated; so what if the tool generates skeleton controllers et. al.? 90% of what you know should be there is yours to do anyway. But that's a huge tangent. :)

loopz 5y ago

I read docs from 10 years ago, still relevant, but just hard to get any value out of. You can see they try to tick all the boxes, but there's very little practical value, direction or any insight. They don't communicate or provide entry steps into a domain, just list stuff very structurally. So much labour seems to have gone into making too much structure vacant of content, following invisible guidelines while trying to please uncaring taskmasters, long gone. I think we're going to go down a more personal road, start caring about who reads what, and just write what would help out, initially, and as reference. Lots of projects on Github do this right, the popular ones, as they convey meaning much better than their competitors. Such examples stand the test of time too.