Why programmers don’t write documentation • Hacker News Board

Re: Why programmers don’t write documentation

#101

Post by mattlondon » Sat, May 01, 2021, 7:46 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…

With respect, you save time making 30 minute videos, but everyone else then wastes time watching your video looking for info.

I prefer it if people just write it down so I can ctrl-f or find it in a web search and get what I need instead of sitting through your videos.

For general "welcome to Team X!" onboarding or training though I agree that videos have benefits. But for day to day knowledge and docs I couldn't think of anything worse, although it seems to work for you and it is popular on YouTube for some things (e.g. Unity game dev content seems be be pretty much 100% video based - if I just need to know how to set up something in the UI like character rigging or wheel physics etc, I often have to sit through 30min videos to find the 15 seconds where they show what buttons to click etc - if it was on a web page I could just skip right to it)

Re: Why programmers don’t write documentation

#102

Post by Arnt » Sat, May 01, 2021, 7:46 PM UTC

I feel like ranting here, but I'll keep it short.

Documentation is a task that is never trivial, but it can be made bloody hard, or not, if you optimise for that. If you ignore documentation as a priority you're optimising for everything else, which implicitly breaks documentation.

But it doesn't have to be impossible, if the trivial aspects as designed to be minimal and the impact on documentation is allowed to dominate other impacts.

https://rant.gulbrandsen.priv.no/udoc/trolltech-documentatio... is relevant, even if most documentation isn't developer documentation. (It's about the Qt developer documentation, which IMO is/was the best developer documentation ever written and maintained by a small team, and no big team has ever done much better either. The hard thinking and work on that was mine.)

The key is that if documentation has such a low status that any other consideration can override it, the result will suck. And if documentation has such a low status that the writing tools suck, so will the result.

Re: Why programmers don’t write documentation

#103

Post by agumonkey » Sat, May 01, 2021, 7:47 PM UTC

metafunctor wrote: post #91

Writing documentation is painful, because it reveals inconsistencies and fuzzy areas in your design. If you're not paying attention, you may associate that pain with the act of writing documentation. In reality, the problem lies with your designs.

Touching an interesting point.. maybe doc is just an ad-hoc rewrite in a different language. Maybe writing your program in different languages can refine the program to the point everything is clear.

Re: Why programmers don’t write documentation

#104

Post by derryrover » Sat, May 01, 2021, 7:47 PM UTC

My experience so far when I wrote documentation for some pieces that I though needed it: - Nobody asked for it - Nobody reads it - Nobody reviews it - Nobody updates it - It takes me over a day to write so I feel quite guilty wasting the time - It is often not clear were I should locate it (as code comments? , in markdown file in repo? In knowledgebase wiki? Some other pile of corporate docs?)

When I talked to my successor about some piece of code a year later he told me how hard it was to refactor and (jokingly) that they pissed of a client breaking a bunch of features while refactoring it. I mentioned the documentation about it, but apparently he did not even notice it existed (seemed also not interested in it).

I guess my fault for not just saving it as markdown in our repo, but instead saving it in a document in our knowledge base (as was according to protocol).

Re: Why programmers don’t write documentation

#105

Post by tlarkworthy » Sat, May 01, 2021, 7:48 PM UTC

pdimitar wrote: post #85

ChuckNorris89 wrote: post #80

Earlier quoted context omitted.

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

It would help if people read them. I write good docs and I often wonder why, as I have to endless redirect inbound queries to the doc. It's ok for my team, they learn, but it's annoying that the whole org never reads anything.

Re: Why programmers don’t write documentation

#106

Post by systematical » Sat, May 01, 2021, 7:50 PM UTC

Software engineers don't do it because lead devs don't enforce it and lead by example. It's not hard. Failure comes from the top down.

Re: Why programmers don’t write documentation

#107

Post by [deleted] » Sat, May 01, 2021, 7:51 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…

[deleted]

Re: Why programmers don’t write documentation

#108

Post by metafunctor » Sat, May 01, 2021, 7:52 PM UTC

agumonkey wrote: post #103

metafunctor wrote: post #91

Writing documentation is painful, because it reveals inconsistencies and fuzzy areas in your design. If you're not paying attention, you may associate that pain with the act of writing documentation. In reality, the problem lies with your designs.

Touching an interesting point.. maybe doc is just an ad-hoc rewrite in a different language. Maybe writing your program in different languages can refine the program to the point everything is clear.

Yep. A different language, a different viewpoint, a different audience. It helps to keep things simple, consistent, and familiar.

If you're designing, say, a RESTful API, it's a good idea to write a couple of client programs in different languages. See what kind of hell you would be putting your users through.

The idea generalizes, as well. Marketing is, sort of, documentation for the value proposition of your business. If you can't make the marketing work, maybe your business fundamentals need to be adjusted instead of hiring a “better marketer”.

Re: Why programmers don’t write documentation

#109

Post by KaiserPro » Sat, May 01, 2021, 7:53 PM UTC

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 knowledge. Want to know how to create a new endpoint? tribal knowledge.

Worse still, we had a class during induction where some ponytailed "10x" said "If you are messaging me asking questions, I can't help other people" I didn't have the bollocks at the time to ask why his documentation sucked arse. There seemed to be a weird pride in the fact that people needed to message him to figure his shit code.

The moral of the story is this:

fuck off with your clever code, spend that effortyou put into learning new languages, or trying a new techniques and put it into developing your writing skills. It takes empathy, organisation and skill. It'll make you a better programmer and a better person.

Re: Why programmers don’t write documentation

#110

Post by Someone » Sat, May 01, 2021, 7:53 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…

I think the solution is the land where documentation is part of the code, so that you have to write it. Ada workbenches tried to get there, as did UML workbenches, but failed.

Lisp and Smalltalk somewhat succeeded, but only for single user systems.

Two questions remain:

Firstly, does that land exist?

Secondly: if so, how do we get there from out local optimum that many, many programmers spend decades on to build higher and higher?