What level of detailing is sufficient for software architecture documentation?

Submitted by Kamal Wickramanayake on Tue, 11/17/2020 - 01:16

Some time ago a team of software developers asked that question from me. What level of detaling is sufficient for the software architecture documentation? Their unique problem was characterized by the following drivers:

  1. They have a suite of software with almost no documentation. This is not a problem for the existing developers. But they face difficulties in adding new members to the team – new members take many months (can even be as high as 2 years) to get a good grasp of the software. So some form of documentation is desperately needed.
  2. Even if they document, they are susceptible to ageing (documents get outdated easily). So maintaining a heavy bundle of documentation is neither a viable solution.
  3. Going forward with no documentation has also become an impossible task.

So what's the optimized level of detailing that should be used? Should the documentation only include abstract architectural aspects? Or should the documentation include design aspects? Or should the documentation done to a level that includes details of function/method calls and so on?

My answer to them was this:

Document to a level that is just sufficient to meet the current and immediate needs. This level depends on the knowledge and skills of the current and immediate consumers of the documentation.

So if new members are added to the team, what do you expect them to know and capable of doing when they join? If documentation should assist new members to quickly become proficient, the level of detailing is determined by the knowledge and skills of such new members.

Kept aside the other forms of documentation, comments in the source code is also of significant value.