
Ask HN: When Is Documentation Bad? - throwaway91911
At work, I&#x27;ve noticed some people are against documentation because, in their opinion, it goes stale so it&#x27;s better to look at the code.<p>There have also been some situations where PR&#x27;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.<p>I&#x27;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?
======
vectorEQ
"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.

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

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

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

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

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

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

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

------
sloaken
Documentation is bad when it is missing.

------
_yeah
When it isn't updated with API changes.

