# Experiments

Over the life of a project, the source code changes significantly. The SCM
accumulates these historical changes. The current source code represents the
sum total of the design efforts and learning that have accrued and ideally
manifests the best effort to create a correct, efficient, and quality software
product. At the same time, the documentation (to the extent it is accurate)
represents an alternate view of the software. Again ideally, there would be a
one-to-one mapping between the software features express in code and those
expressed in the documentation. In other words, one could read the
documentation and know every feature the software provides. That rarely occurs
in practice, but the point is that the usefulness of the documentation is
directly related to how faithfully it represents the current source code.

Some historical information can be retrieved from the SCM. However, this is
typically limited to actual changes. Unless the information is represented in
a change to a source code file or a documentation file, the SCM cannot provide
any information about it. In other words, if the information is never
represented in the repository, the SCM cannot know about it. Also, retrieving
the information may be tedious or difficult.

For these reasons, there is a need for another type of information to be store
in the repository. This information is the design rationale and analysis of
alternatives that we produce while working on the software but which typically
has no representation in either source code or documentation. Both the source
code and documentation typically represent final decisions at a point in time
and do not capture the various alternatives that were examined. Over time, a
great deal of project knowledge is thereby lost.

The doc/experiments directory is a structured place to store the artifacts of
exploring alternatives for implementation of the software. Two main categories
for this type of exploration are correctness and performance. Correctness
information can often be stored in source code changes (i.e. bug fixes) or in
source code comments or documentation. Performance work, on the other hand, is
often performed ad hoc by running some code against a benchmark, tweaking the
code, running it again, and so on until a better version is produced and then
checking in the changes. The source code will represent the changes but not
necessarily the alternatives explored or the analysis of them.
