Ask HN: When Is Documentation Bad? | Hacker News Reader

Ask HN: When Is Documentation Bad?

6 pointsthrowaway9191110 comments

At work, I've noticed some people are against documentation because, in their opinion, it goes stale so it's better to look at the code.

There have also been some situations where PR's to add comments to things were scoffed at. Usually things that would require a developer to navigate 3-5 repositories to find out what certain things mean.

I'm wondering two things: * When is documentation bad? * Have you noticed a trend against documentation (in favor of more pure code reading) at your work?

View on HN

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

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

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.

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

Any sufficiently complicated Go or Java program contains an ad-hoc, informally-specified, bug-ridden, slow implementation of half of Kubernetes.

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

Documentation is bad when it is missing.

When it isn't updated with API changes.

Reply on news.ycombinator.com