It depends on wether you need an overview (black box) or details (white box):

For the overview (black box), you should document or specify building blocks by giving the following information:

  • Responsibility: What does this blackbox do, what task or function does it fulfill? What use-cases, use-case-clusters does it handle?
  • Interface: What is the interface (input, output) of this blackbox, what is its API, what does it require as input and what does it provide as output.
  • Source code: Where to find the source code of this blackbox. That might be the most important entry point, a number of files, directories or packages. Anything that might help a developer to find details.

We call this the black box template, see also question B-8 (black box template).

For details (white box), you should use a diagram with some explanation (aka white box template, see question B-9 (white box template).