Minimum (Lean) System Documentation

Let’s admit it: any form of system documentation is not up-to-date. The moment we start producing it, it is out-of-date.

If that is the case, we should do with minimum (perhaps, lean) system documentation that is kept current. This begs the next question: How little is enough?

If I imagine myself taking over a system from someone else, I believe the minimum/ lean system documentation should contain the following:

Solution Design

• description of the high-level process flow
• description of the main modules/ services in the system
• what are the architecturally significant use cases or main functions of the system?
• what processes/ components make up the system? E.g.
  • Are there web-based applications?
  • Are there batch processes?
• what are the databases in use?
  • What are the primary (entity) tables in use?
• what output is generated by the system? E.g.
  • Are there printed output?
  • Are there output for system integration?
  • Are there messages (emails/ SMS) sent?
• what systems are integrated and what integration patterns are used?
  • what are the triggers for interfacing?
• what user roles are interacting with the system?
• what are the batch jobs and their inter-dependencies?
• what 3rd party – whether freeware, open-sourced, or COTS – libraries/ frameworks are in use
  • what are they used for?

Deployment & Maintenance

• what configuration files are used and location of these files?
• what are the folders (local/ mounted) in use?
• where are the log files located?
• what is the deployment environment (topology) like?