Documenting the decision making process
Communication is an essential human ability.
It is a complex skill to master and one of the keys to efficiency and success.
And even though documentation as a form of communication
in information technology and telecommunications comes in various kinds,
it mostly describes the state of a subject
in terms of "what?" and "how?" but rarely "why?".
The first type in such a dissection would be represented by
standards and specifications;
requests for comments;
guides for users, developers or administrators;
descriptions of any sort that could be references, diagrams, use cases, readmes...;
manifests;
knowledgebases and others... —
which are certainly necessary.
And examples of the not as common second type would include
requirements,
comparisons,
commentaries to source code,
minutes of meetings,
mailing lists...
These usually just complement the software development process.
This note is to suggest or establish an idea of shifting the focus of documentation and
putting decisions in its core.
Beneficial points for consideration are all the general functions of documentation but
applied to the design disciplines in the software development process.
Decisions inevitably become more conscious as they are explicitly documented.
The same unified process is applicable to the project governing as
its documentation is iteratively developed under a source code management system.
It allows observing the development direction.
The context sharing achieves effective collaboration on design tasks.
The clarity of intentions of all the interested parties helps decision adoption,
reduces likelihood of controversy and toxicity.
One notable occurrence of this approach is
Google's C++ programming convention.
It declares specifically that the guidances contain reasoning that
ground discussions, improve clarity and
draw boundaries for when the rules should be waived off.
This is a major step forward even despite
some style sections that contain formatting and naming recommendations
give no explanation.
Another point to discuss is that projects rarely publish
any kinds of requirements, whether functional or nonfunctional.
Putting use cases alongside in the same repository or on an associated wiki
sounds to be a handy practice, so
one is able to follow how
a requirement becomes a set of elements in the API, or
why a library gets chosen over another.
Everything changes: conditions, requirements, technologies and even ourselves.
At some point during the solution's lifecycle there might come a time
to kick off a major redesign and reimplementation or
to sunset the project due to a successful competitor.
Such a time may be recognized during a retrospection of the founding documents.
Given the effort required to create documentation is justified,
this approach draws a perspective of
upgrading a solution from being a system of decisions put together to
a form of communication itself.