Hacker News Reader

Comment by chii | Hacker News Reader

> the most valuable asset of a programmer is his mental model of your system.

Which is actually something a lot of management would prefer to not have. They often want people to deeply document a system, on the mistaken belief that this knowledge could be transferred out easily.

Unfortunately, it's not. Even a well documented system has inherent complexity that only working on the system would reveal. Otherwise, merely reading the source code would allow for a complete understanding and deskchecking of the whole system!

View on HN

The problems with documentation is one, organizing and keeping them up to date is another, and... actually reading it is the other thing. I'm guilty of that myself, because I already assume the documentation will be out of date. But so does everyone else, thinking it's pointless to write something down because it's easier to just ask someone else.

If management cared, not updating documentation with every merge would be a strike, with multiple offenses leading to firing. They don't care. All large development is just slapped together and shipped. By the time the reaper of long term problems comes, the problems are too big to fix.

We can also break it down even more, managers are only allowed to pick one of the mutually exclusive options:

- Well documented, well maintained code that everybody could work on

- Quickly finished projects that nobody ever touches again, but only the programmer(s) have a mental model of it

The first option is more expensive at first, but way less expensive if you happen to have to rewrite it from scratch at some point (and if you are not maintaining and document it, that moment will come and it might not come at a point in time that fits the schedule).

The second option is less expensive first, but it will bite you in the arse if the programmer(s) are gone or forgot how it is done.

Everywhere else managers try to minimize risks, here they often just don't aeem to get the trade-offs involved.

The missing bit you forgot is that even if the first option was chosen, it very quickly devolves into the second option, whether the managers like it or not.

Reply on news.ycombinator.com