Perfect documentation
Mariusz Saramak
41

Hey Mariusz,

It was not me who wrote the bottom arguments, but I must say that I agree with him also.(http://softwareengineering.stackexchange.com/users/34148/nochance).

I must say, personally, it makes sense to document. Scaling an application to a certain size just requires some inline documentation. Simply stating ‘just read the code, it’s in the code’ won’t hold anymore.

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:

  1. Not all developers have the same IQ — You want every one to get it not only smart John.
  2. Not all code is obvious, complex algorithms are not quite readable by all.
  3. Business rules, while may be readable, may not alone show why they are there. Take for example this line in a reporting application:
  4. Finding out details take long time, it is a waste of business money.
  5. 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.).
  6. Documentation should help you understand logs and whether the results are correct or not.
  7. 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.
  8. 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.