Why is code documentation such a painful process?

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

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.

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.

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

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.

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