Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Why programmers don’t write documentation

kislayverma.com

Post reply on HN
Print view View original

111–120 of 153 posts

Re: Why programmers don’t write documentation

#111

Post by pdimitar »

tlarkworthy wrote: post #105
pdimitar wrote: post #85

Earlier quoted context omitted.

> 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.

I am one of the guys who appreciates docs but also wants pointers at the start.

Just giving me an URL with 50-100 pages of docs is not good enough. Give me something like "when you are just starting", "when you want to tackle a ticket involving X" or "when you need to edit the deployment script" etc.

In my last job the architect was always irritated with me because he wrote a bunch of docs but never organized them or just gave a proper small index -- seriously, just 15 lines of text with links so you know where to click at the start would have been enough! -- but then somehow the team was at fault for "not reading the docs".

So there's a balance. I don't appreciate being given a book and being told "figure it out", which is what happened in my last jobs. Sigh.

Having a small page with starting pointers I always found priceless and is what I do in my work and I've had people contacting me 5 years after I left the job to thank me for it.

Re: Why programmers don’t write documentation

#112

Post by _y5hn »

tlarkworthy wrote: post #105
pdimitar wrote: post #85

Earlier quoted context omitted.

> 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.

There should exist a need, for pouring labour into something, to make it worthwhile. Also, when the need is there, it is much clearer for who and what purposes you're providing knowledge.

It's not laziness if it's efficiency, or love.

Re: Why programmers don’t write documentation

#113

Post by lamontcg »

I tend to not write documentation because with a massively understaffed team it is futile. If we had 10 devs working on this project we could all spend a month focusing on docs and significantly move the needle. Right now I'd have to slave away for 10 months to get the same amount done on the docs backlog. So it doesn't happen, because I want to write code and not docs all day long. When I look at the many person-years of backlog of documentation that needs to get done I just get demoralized and that makes me not care about any of it. Want more documentation? Hire more devs.

And putting barriers in the way so that I can't code without docs just pisses me off when I'm demoralized. Make it take twice as long to code anything and I'm definitely thinking about looking for other work.

Re: Why programmers don’t write documentation

#114

Post by droobles »

I'm writing documentation now and it's not bad, just takes a long time and keeps me from coding more features. I try to add screenshots and relevant links to helpful blogs Luckily, my role on the team is more of a consultant and technical researcher, so this work provides a lot of value as we anticipate onboarding more junior engineers in the next phase of our project.

Re: Why programmers don’t write documentation

#115

Post by TeMPOraL »

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…

> 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 pieces of institutional knowledge are missing.

I've already resigned to the fact that any changes in the codebases I tend to work on involves spelunking through past commits, trying to git-blame my way into knowing where some suspect feature came from (and thus who to ask to explain it to me).

But few things annoy me more than when, after an hour of poking around and following code being moved across files, I finally arrive at the commit that introduced the thing I'm after, only to discover that the entire commit message is "refactored $foo", or "fix $blah". Oh, and the commit touched 20 different files, implementing 3-5 different things, and the author left the company a year ago.

So if you aren't doing it already, then for the sake of everyone (including yourself few months from now): please, write descriptive commit messages, while everything is still fresh in your memory. By descriptive, I mean at least a bullet point list of everything that was changed, and why. Even if it means repeating some of the stuff from a ticket or a discussion somewhere - because none of these things will be available or easy to find few months later.

Something like:

  Add feature Foo

  This commit implements feature Foo, as per ticket #12345:
  option $foo controls whether or not Flux blergs or blargs;
  in the latter case, $this and $that will happen.

  * Configuration files have been updated with the new paramter.

  * Flux Controller no longer looks at unobtanium to determine
    the type of blerging to perform.

  * The above implies that checking Flux for the type of blerg
    is now speculative, and should not be relied on in the future.

  * A new utility Asdf has been added; it provides common functionality
    for blarging.

  ...
Etc. You get the picture. It's quite easy to write a message like this when committing - it's essentially a polished brain dump. And its usefulness will be immense the next time someone has to work in this part of the codebase.

Re: Why programmers don’t write documentation

#116

Post by truetraveller »

TeMPOraL wrote: post #115
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…

> 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 pieces of institutional knowledge are missing. I've already resigned to the fact that any changes in the codebases I tend to work on involve…

Hey, nice commit template. Will be using something like this. Thanks!

Re: Why programmers don’t write documentation

#117

Post by pdimitar »

TeMPOraL wrote: post #115
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…

> 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 pieces of institutional knowledge are missing. I've already resigned to the fact that any changes in the codebases I tend to work on involve…

I do that for big commits. But usually I prefer much smaller commits whose 1-2 lines of text are enough.

I reserve those bigger texts for PR descriptions.

I found those to be a nice balance, most of the time.

Re: Why programmers don’t write documentation

#118

Post by _y5hn »

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

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.

Re: Why programmers don’t write documentation

#119

Post by TeMPOraL »

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 is not modified.
  //! Returns a Bar that is Z.
No knowledge or skill needed. And will make everyone's day nicer.

I'm not sure what to do about lack of care in a team/company, other than trying to promote it by example.

Re: Why programmers don’t write documentation

#120

Post by pdimitar »

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…

One could argue that the realization that this should be done in the first place is the skill your parent commenter was talking about.
Post reply on HN