Hacker News Reader

People writing essays about software that are bound to get outdated and will never be read by anyone.

I write a lot of documentation entirely with the awareness that no one else will read it. I write it for myself. I don't want to have to remember the intricacies of a system. I want to write things down, then move on immediately, and have the security of something I can refer back to if I need it when I revisit the system.

But doing so is your personal preference, you (i hope) are not required to do so. Some people find it easier to organize their work differently or not at all. Some people are astonishingly productive despite not writing anything down, ever.

What if the teams changes? Intricacies must be documented despite that probably nobody will ever read it. Somebody might depend on it.

Writing code is more about communicating how to solve a problem than just solving a problem, that's how I view it. If you don't communicate, nobody except you will ever understand it. It might be that you don't need to document a lot, maybe most is obvious if the key parts are sufficiently explained. But it's vital and sometimes it's better to write a bit more than a bit less. A thing is, outdated documentation might be worse than none, so it's a delicate balance.

What if the teams changes?

Yeah, documentation will definitely help in this case. With it, you can swap teams and even companies, and it still works! This only fails in companies which do not review documentation and have no routine for keeping it in sync and testing it on e.g. newcomers, like you do for backups. Cause otherwise it is as good as never tested six months old backup.

It's always fun if a product is based on 20 year old code where there are parts that nobody can touch because there's nobody around who understands what's going on there. I once saw a flight-training software (I think it was for helicopters?) where the physics engine just didn't get touched because they don't know what's going on. Every change was essentially a hack around this blob of years old, highly optimised but totally incomprehensible C.

EDIT: It might have even been fortran code. The rest of the project was C++

I once saw a flight-training software (I think it was for helicopters?) where the physics engine just didn't get touched because they don't know what's going on.

This is an interesting case, because it's something that I probably wouldn't document. Code should be readable. If you're writing down how your code works in a document then something is wrong with the code. Documentation can't fix an incomprehensible codebase. I document how algorithms work, what the business logic is for things (which is another algorithm really), how applications work in a 'data flow' sense, what integrations there are with external services and how they work, what things mean, and so on.

Normally working out how a complex piece of software works from only the source code is called reverse engineering.

I've encountered this "readable code means I don't have to document" idea before. I have no time for it, it's just wrong:

1. Important things aren't easily visible in the code, most commonly why the code does a particular thing. "Readable" code, which is a very subjective standard, can only tell you what it does but not the underlying rationale.

2. Writing docs often exposes the fact that the way the code works, or is expected to be used, doesn't make sense or is sub-optimal. If your docs include lots of caveats or explanations of nonsensical behaviour then it's a good hint you should go back and think again.

3. Figuring out stuff by reading the code is often drastically slower than reading the docs. That's why all professional APIs have good docs and people grumble and moan when expected to use code that doesn't.

4. The sort of people who argue this, in my experience, often don't actually write readable code, they just tell themselves they do.

But doing so is your personal preference, you (i hope) are not required to do so.

I am required to in the sense that I define the policy about what gets documented on my team, and I said we write documentation about everything.

This type of documentation is the only kind I have positive experience writing. Tutorial-like documentation is another kind I have positive experience reading.

> The author does not complain just about writing documentation, but about writing an unproportionate amount of it that presumably isn't being read by anyone. I've seen that happen. People writing essays about software that are bound to get outdated and will never be read by anyone. In systems that are disconnected from the source code.

This has been the norm more often than not in most companies, especially larger ones. Hence the Agile Manifesto, written by people who've been there again and again.

And still, working in company that does not document what the system does, it sux massively more.

Because end result is that no one knows how to use our own software. You dont know what it is supposed to do, so it is impossible to keep that stuff working. It takes ridiculous amount of time to configure anything or reproduce bugs, because you need multiple calls to find the one person who barely remembers.

Also agile manifesto is 20 years old. Agile is literally what most large dysfunctional companies do these days. It does not have no new solutions to actual real problems of companies, because it is old.

No-one ever suggested not to document!

The comment I replied to says "inappropriate amount of documentation", the Agile Manifesto says "comprehensive documentation".

That's the problem. Months, if not years, spent on pages after pages of comprehensive documentation that does not add any value and is obsolete by the time you start writing actual code.

Lastly, the age of something is not a relevant criterion. Not much has actually changed over the last 20 years. What has changed is the explosion of web-related software, which is actually the best suited for the ideas behind the Agile Manifesto.

> That's the problem. Months, if not years, spent on pages after pages of comprehensive documentation that does not add any value and is obsolete by the time you start writing actual code.

This picture is not any real company I ever worked in or real company I heard of from friends. Literally, not even before agile manifesto.

> Not much has actually changed over the last 20 years. What has changed is the explosion of web-related software, which is actually the best suited for ideas behind Agile.

That is not actually true, really. A lot did changed.

This also glosses over something else. Comprehensive documentation can even be really well documented code!

And in small corps, there's the "guy who wrote it" was "hit by a bus" scenario. It doesn't matter how dilligent, or how faithful someone may be when they leave, eg walking a replacement through the codebase can't happen of you're dead!

This is how I document. I think about being hit by a bus, and what would this corp do? A replacement hiree do? See?

Not doing this is, IMO, should be criminal. Like a CFO not keeping books.

I've never seen anyone having to write a 50-page document just for "some little code", unless the author's definition of "some little code" is drastically different from mine. Without anything to back it up, that statement comes across as a huge exaggeration.