Why programmers don’t write documentation • Hacker News Board

Re: Why programmers don’t write documentation

#31

Post by pithon » Sat, May 01, 2021, 5:41 PM UTC

aphextron wrote: post #26

It's also generally useless. If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on…

Writing is thinking and oftentimes just being able to explain in words what a thing does, should do, and should not do- has tremendous value as part of the design process before any code is written.

Re: Why programmers don’t write documentation

#32

Post by billytetrud » Sat, May 01, 2021, 5:42 PM UTC

aphextron wrote: post #26

It's also generally useless. If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on…

Documentation is not generally useless. Most code is used far longer than it's intended life, most code is read far more often than it's changed, and documentation can save literally hours and days of struggle. Word of mouth knowledge transfer is abysmal at keeping critical knowledge alive. Nobody ever knows anything about legacy code, and it's because no one wrote documentation. Please stop telling people documentation isn't important

Re: Why programmers don’t write documentation

#33

Post by xwolfi » Sat, May 01, 2021, 5:43 PM UTC

dboat wrote: post #19

waheoo wrote: post #15

Earlier quoted context omitted.

It's not bs. They said should, not must. Yes there are trade offs with everything you do in IT, one of them is creating a shit place to work in the name of speed. It might work for a little while but eventually you're going to realize you're shitting where you eat.

This was my attitude as well for much of my career, and it was a mistake. The "correct" decision depends on the state of the business and your resources at the time. And nothing else.

Yes, I've worked mostly in money losing startups, but since I work in a $ billion-profit investment bank I saw the difference. It's better to waste money on technical debt crisis down the line than have no money to waste because of thousands of devs all being perfectionists locking each other.

Small startups seem to reach this stage eventually and in big companies, management is acutely aware of it, and breaks every attempt at correctness-over-business-rationality, under the teary cries of the autists, sometimes :D

Re: Why programmers don’t write documentation

#34

Post by billytetrud » Sat, May 01, 2021, 5:44 PM UTC

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.

Re: Why programmers don’t write documentation

#35

Post by abc_lisper » Sat, May 01, 2021, 5:45 PM UTC

aphextron wrote: post #26

It's also generally useless. If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on…

Under this kind of plausible argument, lie all sort of insects (bugs) in the dark. If people can make time to write tests, so should they write documentation. There is inordinate amount of frustration, productivity loss, and regression associated with having poor/outdated/no documentation.

Re: Why programmers don’t write documentation

#36

Post by enraged_camel » Sat, May 01, 2021, 5:53 PM UTC

billytetrud wrote: post #32

aphextron wrote: post #26

It's also generally useless. If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on…

Documentation is not generally useless. Most code is used far longer than it's intended life, most code is read far more often than it's changed, and documentation can save literally hours and days of struggle. Word of mouth knowledge transfer is abysmal at keeping critical knowledge alive. Nobody ever knows anything about legacy code, and it's because no one wrote documentation. Please stop telling people documentat…

I do agree that code is read more than it is written. At the same time, there's the adage: "treat your data as permanent, and your code as transitory."

Re: Why programmers don’t write documentation

#37

Post by pfortuny » Sat, May 01, 2021, 5:53 PM UTC

aphextron wrote: post #26

It's also generally useless. If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on…

You should think about all the cobol software out there and how your ideas contrast with it.

Re: Why programmers don’t write documentation

#38

Post by dt5702 » Sat, May 01, 2021, 5:56 PM UTC

This article is a bit of a non sequitur. I generally agree with the points raised but the real problem is whether documentation is given enough time within the development cycle. In my experience it isn’t.

The point of documentation is to communicate to others how to keep developing a code base - what is does, how it does it etc. What form the documentation takes can be fluid, a full fledged wiki or a single readme.md file can fulfill the same role just as well! Some documentation is better than nothing, so start small and then improve it over time.

Re: Why programmers don’t write documentation

#39

Post by saiya-jin » Sat, May 01, 2021, 6:03 PM UTC

aphextron wrote: post #26

It's also generally useless. If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on…

Not really. Maybe in your very narrow environment, but all the multinational corporations I've worked in past 17 years on, situation is way more complex. Software often outlives people who created them, sometimes even whole teams originally responsible for it.

Suddenly you have a Pune team managing all environments including production, who have rather vague about yet another system thrown on them due to that smart idea called outsourcing. Sure they can change a thing or two, but corner cases can and often do bite hard. Code itself, while describing well what is happening, often doesn't contain much info about why. Or further effects of decisions. Full picture of whole integration involving 20 or 100 systems etc...

Another issue in huge companies spread across the globe is the ability to actually connect with relevant team, and their reluctance to share crucial info. A job security political game is not foreign to devs in some cases. I've had my request for source code of one of our internal security libs, the cornerstone of all of our inter-app authentication, refused with justification that its safer for the company to not share it even within company. Mind you, the .jar wasn't obfluscated at all so JAD got me to almost-compilable version so that effort wasn't even half-assed.

Man, I could spend whole evening telling stories how documentation can be great. Even incomplete, not completely up-to-date one can save your ass from time to time. And tons of time on top of that.

Re: Why programmers don’t write documentation

#40

Post by wwweston » Sat, May 01, 2021, 6:05 PM UTC

ajcp wrote: post #8

> Writing is a tough, demanding task. It requires organizing our thoughts clearly, examining them critically, and expressing them clearly. While the expressing part can be simplified to some extent (depending on the quality of writing required), all three steps are taxing when done properly. Wow, almost sounds like some other aspect of a job a software engineer is required to do... > If a developer doesn’t write docu…

> Wow, almost sounds like some other aspect of a job a software engineer is required to do...

Which I think is the real problem. Writing/modifying code can't be ignored; the resulting behavior of technical systems absolutely depends on doing that.

You can argue that the desired behavior of human system also depends on good writing and you're correct. But the connection of the input and output is much more opaque, the social conception of the role is focused on the behavior of technical systems, the incentive structures are therefore focused on the behavior of technical systems, so when there is more to do than can be done writing docs will not make the top of the priority queue.