Hacker News Reader

> 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 documentation?

Let's face it, most web facing SW nowadays is like fast-food. Investing tons of time in writing quality documentation would by like a triple Michelin star chef writing a 20 page article about a doner kebab.

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

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.

my docs are a single page full of one liners for practical issues that have organically arisen several times over the years, with a table of contents at the front.

As I said, I write good docs, but no-one will read them until they have been caught out 3 times asking obvious questions had they gone to the doc first. If I am not around, I know the docs will be abandoned immediately despite it representing a tome of hard won knowledge that saves an incredible amount of aggregate time from never needing to figure out how to do the same task twice.

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.

> Let's face it, most web facing SW nowadays is like fast-food. Investing tons of time in writing quality documentation would by like a triple Michelin star chef writing a 20 page article about a doner kebab.

A lot depends on the project size and expected lifetime (honest expected lifetime). But you can look at it from another perspective: the most basic internal documentation, like commit messages explaining why something was done, interface-level comments explaining what a function or class does, internal comments explaining the tricky bits of implementation - they all increase velocity of product development. So it's a good thing to do on team level.

(But it's kind of a "pay it forward" thing. You may not benefit much from your own comments, but you'll be thankful for the ones your co-workers leave.)

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.

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.

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.

> they rely on esoteric knowledge to build defensible moats around their seniority

Sadly you are correct. Job security and thus gatekeeping are the higher priority.

So yeah, yet another case of perverse incentives. :(

> Ultimately, this is why I think we need compiler assistance so that stuff like docs can be enforced in CI unilaterally.

Completely agreed, plus declarative programming. At 41 I am already sick to my stomach about having to manually write boilerplate. Tooling helps only a little and is hugely overrated; so what if the tool generates skeleton controllers et. al.? 90% of what you know should be there is yours to do anyway.

But that's a huge tangent. :)

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.

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

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

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.

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?

I guess indeed many find it bloody boring. A chore to be dodged if possible. And also when doing some documentation work, because people are so deeply into the subject matter, they feel many things are obvious and need no further elaboration.

Yep, and that's why being sympathetic and able to put yourself in the shoes of an outside reader are very important soft skills for a programmer.