It is useful to try and capture the story of a predicate or a feature in the docs?

Not so sure. I have this obsession with side-stepping hard problems. (Some call it “laziness”). Yes, it is difficult, expensive, time consuming to write technical documentation, and to keep it up to date for software in particular. However, there is a way to side-step the problem; it isn’t novel as such and I don’t expect to write anything that you don’t already have experience with. [Disclaimer: I am currently testing this approach in practice. However, I am not using a scientifically rigorous approach because I cannot afford it, so the value of whatever “wisdom” I am dispensing is questionable…]

Do not write technical documentation that reflects the codified parts of the system.

Do not write specifications in a natural language.

Do not document what your program/module/class/function/predicate… does.

Do not make diagrams and other visualizations that simplify and obscure the behavior of your system. (Here, “system” is your software and all the upstream software, running on a concrete machine, within the context of a larger system with practically unpredictable behavior.)

You will of course do all of these things as you develop and maintain your system. It is unavoidable that in the process you will produce many artifacts of fuzzy nature. Their purpose is to help people unite towards a common goal, share a narrative to give direction, and motivate. Once you have codified the behavior, you can and should discard those artifacts from your “documentation” and keep them only as a part of an audit trail or proof of work.

There are two underlying assumptions to my argument.

  1. The codified parts of your system are available for inspection; this means both readable by humans and crucially, in practice executable on a concrete machine within a predictable environment, ie they are reproducibly testable.
  2. You do provide enough documentation, strictly for humans, that delineates the purpose of your system within some larger context. There, you can and should go wild with your diagrams and visualizations, as long as you remember to leave out all the codified parts.

This is my current understanding of the issue of technical documentation, very superficially. I tried to keep it short and purposefully omitted a lot of relevant detail. For example, the definition of a “concrete machine” is quite fuzzy itself. I don’t mean a particular CPU architecture, I mean any “machine” that is in practice a black box that behaves somewhat reproducibly. Under this definition, even a system built with some (or several) cloud service provider’s product offering is still a “concrete machine”.

I reached my self-imposed word count limit. Thank you for your attention :slight_smile:

1 Like