Why programmers don’t write documentation • Hacker News Board

Re: Why programmers don’t write documentation

#151

Post by indentit » Fri, May 07, 2021, 5:28 AM UTC

massung wrote: post #99

Something the author didn't dive into - which is very important - is the audience of said documentation. In my 20+ years documentation is pretty much essential, but there is definitely a skill in documenting for a particular audience: * Internal, non-technical users; what does the code do, why was it written, who currently owns it, when should it be run, how to run it, and what to do in case of failure. The more acce…

> Programmers are comfortable with just being pointed to a repo and text files, while non-programmers want WYSIWYG docs somewhere central, which is the last place most programmers even think about.

Yup, I think if you are forced to use central WYSIWYG documentation, it makes sense to link to it from the readme in the repo. There's nothing worse than having documentation but being unable to find it or being unaware of it - it may as well not exist, and was a waste of time writing ;)

Re: Why programmers don’t write documentation

#152

Post by billytetrud » Wed, May 12, 2021, 7:22 AM UTC

cudgy wrote: post #53

billytetrud wrote: post #34

Documentation is so important. The problem with documentation is that engineers don't seem to understand it's benefits. I think one reason is that so much of the documentation out there is so poor quality that engineers think documentation can't be good quality.

Ding ding ding ... you summarized most of the reasons why but your conclusion is wrong. What does not and likely cannot exist is not important.

??? What do you mean "what does not and likely cannot exist" ?

Re: Why programmers don’t write documentation

#153

Post by dragonwriter » Wed, May 12, 2021, 7:36 AM UTC

TeMPOraL wrote: post #119

KaiserPro wrote: post #109

Documentation is a skill. Like any skill it takes practice. I have moved to a FAANG and their documentation is downright fucking awful. _everyone_ just writes code, with lots of "clever" bits, and doesn't bother to fucking comment. Not only that because people don't even _comment_ their code, the wiki is a total shit show. Want to know how to use a Queue? tribal knowledge. want to know which DB is best for x? tribal…

> Documentation is a skill. Like any skill it takes practice. The type of documentation you described - code comments and wiki entries - they don't need practice. They only need care. If you know how to write a function that takes Foo and transforms it into Bar under conditions X and Y, you also know how to just append this above it: //! Transform Foo into Bar //! //! Foo must be an X-ing Quux adhering to Y. //! Foo…

> The type of documentation you described - code comments and wiki entries - they don't need practice.

Yes, they do.

> They only need care.

They need that, too, but “care” is what gets you to apply what you know of how to do it rather than neglecting it, but practice (and interactive practice with feedback, specifically) is how you develop the skill to make useful comments, and ideally only useful comments.

> If you know how to write a function that takes Foo and transforms it into Bar under conditions X and Y, you also know how to just append this above it:

Well, mechanically probably you know how to. But absent relevant practice you might not know that (assuming, for the sake of argument, that this is correct in context — and in many cases, IMV, it wouldn’t be as much of that seems to reiterate information that is contained in type signatures and thus violate the principle of single source of truth if placed in comments) you should prepend comments with that content, rather than none or some other content foe the function.