Ask HN: Why is code documentation such a painful process? - Kesava1312
======
cborenstein
In my experience, code documentation is painful because people often try to
maintain perfectly comprehensive formal docs and the expectation is too high.
Aiming for perfection instead of iterative improvements can feel intimidating
and painful.

I recently wrote this blog post on how you can use lightweight daily habits in
git and [https://bytebase.io](https://bytebase.io) (I'm one of the creators)
to avoid the dreaded "Docs Overhaul" that seems to happen every couple of
months.

Blog Post: [https://medium.com/better-programming/daily-habits-to-
turn-y...](https://medium.com/better-programming/daily-habits-to-turn-your-
git-history-into-valuable-documentation-15113e1bf312)

The main idea is to capture small chunks of context as part of your regular
coding routine. This can be in a git commit message if it closely relates to
code or in an external knowledge sharing tool if it is higher level context.

------
afarrell
Writing feels fluid to me when I think I know what I am talking about and I
can imagine someone what parts of my writing someone wants to pay attention
to.

When writing documentation, you often either:

1) Know the system very well -- So it is hard to know what the reader needs to
know.

2) Don't know the system well at all -- so WTF do you write?

Documentation is better written as a pair between an engineer familiar with
the system and an engineer who has self-confidence, passing familiarity with
the languages, and no knowledge of the system.

Product idea: As two engineers pair-writing documentation, I want to turn on a
product that records what we say and where the senior engineer navigates in
the codebase into a very-rough first draft of documentation. Look at the
Otter.ai API.

------
thereyougo
I actually read a great answer on Stack Exchange about it recently:

>In my opinion, any system that is used productively and is supposed to be
maintained by people, should have documentation at reach of those people who
are responsible for its support. The reason is, simply because:

Not all developers have the same IQ - You want every one to get it not only
smart John.

Not all code is obvious, complex algorithms are not quite readable by all.

Business rules, while may be readable, may not alone show why they are there.
Take for example this line in a reporting application:

if (lastname>="ZZ") then goto loop it is somewhat clear to the reader what is
happening but not why this is the case?

Finding out details take long time, it is a waste of business money.

Dependency between pieces of the system may not always be obvious. Especially
in batch processes where each job looks like an independent program but the
execution sequence is a package that must be processed according to certain
rules (like monthly runs, etc.).

Documentation should help you understand logs and whether the results are
correct or not.

When you understand the function of each component you can answer business
questions. Say Suzan calls from accounting and asks why are we missing 5
checks this month? Some programmers may respond, well, I ran the job and gave
me no error - This can't help Suzan. If you know which part of the system does
the data extraction for processing the checks and then know what are business
rules applied to qualify a check to be printed you can provide an useful
answer - Assuming there were no bugs.

Remember that documentation go way beyond the comments that are inserted in
code. They include ERD, Business Requirements documents, Design documents,
etc.

In short: good documentation gives the developers the necessary control to
maintain a system.

source:
[https://softwareengineering.stackexchange.com/questions/1217...](https://softwareengineering.stackexchange.com/questions/121775/why-
should-you-document-code)

------
Vesuvium
Because writing documentation after the implementation is hard and error-
prone.

I've found that writing the documentation before and using it as guide for
developers works best.

------
type0
It gets outdated fast, it becomes messy and it's difficult to explain all
concepts with words etc

~~~
bluestreak
I totally agree with this. Good codebase evolves all the time thru constant
refactoring. Looking after code documentation in this context is a pain.

Complex algos should be covered by tests and not so much by comprehensive
documentation.

Code documentation works well on external API, which is meant to be relatively
static.

