Why programmers don’t write documentation • Hacker News Board

Re: Why programmers don’t write documentation

#81

Post by __jem » Sat, May 01, 2021, 7:18 PM UTC

pdimitar wrote: post #75

It's bloody hard, you say? Hm, maybe in part of the cases, but you know what else is even harder? Getting onboarded in a new project and having zero clue why X is written like that, why is Y is where it is and why Z is using a 10-year old thread-pool scheduler that is grossly inefficient. And you have to deliver feature A and bugfix B and you might collapse the house of cards and of course, critically important piece…

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.

Re: Why programmers don’t write documentation

#82

Post by mkl95 » Sat, May 01, 2021, 7:18 PM UTC

It's bloody hard to write documentation at some small companies, because management want you to put out fires and maintain buggy legacy codebases most of the time. The rest of your time is spent in meetings and actual development. At these companies writing documentation is brushed aside and developers are supposed to "figure it out".

Re: Why programmers don’t write documentation

#83

Post by SavantIdiot » Sat, May 01, 2021, 7:20 PM UTC

You know what's worse that writing documentation? Keeping it up to date with software changes! Even worse if it has a GUI and all of the images have to be refreshed for every tweak. I've tried a number of auto-document tools, Doxygen, NaturalDocs, ReadtheDocs., and they just add another layer of pain. IMHO. In 30+ years I have not found a satisfactory solution, except to budget time & resources for constantly, incrementally reviewing & updating docs.

Re: Why programmers don’t write documentation

#84

Post by __jem » Sat, May 01, 2021, 7:21 PM UTC

The answer here is to lean on the compiler. I _love_ rustdoc and think the fact that it can compile all your example code and links is awesome!

Re: Why programmers don’t write documentation

#85

Post by pdimitar » Sat, May 01, 2021, 7:21 PM UTC

ChuckNorris89 wrote: post #80

pdimitar wrote: post #75

It's bloody hard, you say? Hm, maybe in part of the cases, but you know what else is even harder? Getting onboarded in a new project and having zero clue why X is written like that, why is Y is where it is and why Z is using a 10-year old thread-pool scheduler that is grossly inefficient. And you have to deliver feature A and bugfix B and you might collapse the house of cards and of course, critically important piece…

> critically important pieces of institutional knowledge are missing And the guys who have it are the "10x devs" in that joint. >Or they find it "boring". Or, it doesn't count much towards your annual performance review so then why bother if you have enough stuff on your plate that does count towards your performance review. When was the last time someone got promoted because they write really, really good internal d…

> Or, it doesn't count much towards your performance review

Oh I agree that most managers have no clue about this metric so doing it well will likely mark you as the slowpoke of the team.

The way I address this is that I budget the time for those "extra" activities beforehand. I just find it a professional courtesy to leave good docs for the next person after me -- or new hires while I am still there.

Not sure there's a way to actually incentivize programmers to write good docs.

Re: Why programmers don’t write documentation

#86

Post by strokirk » Sat, May 01, 2021, 7:23 PM UTC

hesdeadjim wrote: post #6

I’m in games so the visual element often forces this, but I’ve moved our team to making a lot of video content, both for PRs and for much of our “documentation”. I’ve always preferred reading, and the trend to everything being on YouTube has driven me nuts, but I’m a convert to this method for a few reasons. First, it’s fast. I can sit down and make a deep dive video in 30 minutes and not have to sit around writing a…

This is a great idea! I'm a visual learner, and better att speaking than writing, so this is probably something I should try to do more.

I've only done it once so far, but I created a short video with Loom to demonstrate how a bug could be caused in the PR that fixed it.

Searchability is probably what would suffer from this approach, and the fact that text is much easier to edit (both for succinctness and correctness).

Re: Why programmers don’t write documentation

#87

Post by pdimitar » Sat, May 01, 2021, 7:24 PM UTC

__jem wrote: post #81

pdimitar wrote: post #75

It's bloody hard, you say? Hm, maybe in part of the cases, but you know what else is even harder? Getting onboarded in a new project and having zero clue why X is written like that, why is Y is where it is and why Z is using a 10-year old thread-pool scheduler that is grossly inefficient. And you have to deliver feature A and bugfix B and you might collapse the house of cards and of course, critically important piece…

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 bas…

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.

Re: Why programmers don’t write documentation

#88

Post by __jem » Sat, May 01, 2021, 7:25 PM UTC

Nextgrid wrote: post #72

The problem with documentation is that the infrastructure/tooling for it is terrible compared to the infrastructure for code. Documentation is often in external systems (Confluence, etc) which lack version control and are hard to keep in sync with the code, and those systems are often extremely slow (especially considering all it does is handle text) and the user experience is terrible (no Markdown support, mandatory…

highly recommend using plantuml, which allows you to version diagrams as text. the diagrams are super ugly but it's totally worth it.

Re: Why programmers don’t write documentation

#89

Post by noir_lord » Sat, May 01, 2021, 7:25 PM UTC

Nextgrid wrote: post #77

noir_lord wrote: post #74

Earlier quoted context omitted.

I just put a /docs directory in the root of the project and everything inside that is vanilla markdown. It brings it under source control and if the person reading it doesn't know markdown they likely shouldn't be reading it anyway.

In all the places I've been that's now how things were and there wasn't any interest in changing it, so instead they kept going with a shitty and outdated Confluence/etc.

For the really high level stuff/business stuff that pretty much does have to live on confluence, I just link to the index page from markdown.

It's a little bit of work on my part keeping that bridge up to date but that should (imo) be part of a leads job.

Re: Why programmers don’t write documentation

#90

Post by __jem » Sat, May 01, 2021, 7:28 PM UTC

pdimitar wrote: post #87

__jem wrote: post #81

Earlier quoted context omitted.

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 bas…

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…

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.