Ask HN: When Is Documentation Bad?

"its better to look at code" might be valid for tiny projects, but good luck making sense of million lines of code in thousands of files.... i'd rather have a document with proper chapters / sections. it will always be easier to read. The problem is not with documentation ,but with the fact people are too lazy / distracted to update it along side their code. (i.e for every code you write, have the documentation open and verify it's still matching... / alter it where needed)

documentation can also highlight easier program flow and other things which might not be clear from 1 code file or module. You could add such information in comments, but then you would need to be find that certain file with specific comments instead of just looking and ctrl+Fing in a document...

i feel many people are against documentation just because they don't like to write it for whatever reason (maybe they just don't know how to concisely describe their own code...)

if you look at companies who manage and own large code bases like HP and IBM, they have BIG documentation, and it's there for a good reason.... it's crucial to have.

not having documentation is like programming something without any technical / functional design. it will become a mess sooner or later.

It's never bad. The people you work with are wrong.

The thing to remember is, just like code, the work of documenting something is never done. It's an ongoing piece of work. It takes effort to maintain docs just like it takes effort to maintain code.

When it's poorly written, out of date, or impossible to search.

Imagine trying to understand kubernetes from code :D Maybe we can come up with "real programmers ..... " haha

When it isn't updated with API changes.

Documentation has been one of the pain points of my programming career. I've worked on some big projects with software that can't afford to fail and needs to meet a bunch of requirements. All of them only had user manuals and zero documentation.

A kind of documentation that I hate is documentation that just explains what a function does (adds x to y) instead of what business/real world reasons that logic exists (adds x to y because of "Z"). Explaining the why vs how is what documentation should be doing and I can understand why so many programmers shrug documentation when all they are doing is writing the how in non parse-able form instead of expressing why.

[personal opinion incoming] It depends what sort of code you are writing. Documentation can tell you

-> What a piece of code does => Properly written code can be self sufficient in that if the domain is not too complicated.

-- Why a piece of code exist => Git history and commits linking to user stories can also serve that purpose, to an extent.

-- How the code is architectured, best practices etc. => I don't think there is an equivalent for that just using code.

In my own opinion (front end dev) I would:

- leave comments in the code only if it's doing something unexpected, because of a weird edge case, i.e some sort of hack - Create documentation on the overall architecture of the code. Keep that up to date if new pattern emerge. - Create documentation on specific area of the code, if they are complexe enough. "How we handle this feature" sort of stuff.

And I would keep it at that. That is for a product. If you work on a library / framework (even internally), then you want a full API documentation.

Backend has different requirements.

Documentation is bad when it is missing.

If there is no policy or effort to maintain it in a system that is rapidly changing, then documentation that is not kept up to date, can mislead people.

Say you decide to hire an engineer for 150k a year. If all he or she has to learn from is stale documentation, you are wasting time and money. The engineer may even start to approach the problems to solve in entirely wrong ways.