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.

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.

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.

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

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.

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.

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

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.

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.

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.

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.