- Code is opaque.
- When a programmer changes N = A \* B + 1 to N = A \* (B + 1),
the rationale is anything but clear. A bug report is needed to explain
the intent of the change.
- Documents are transparent.
- When a writer changes "the system is intended to do X" to "the system
is not intended to do X", the meaning of the change is immediately
obvious to the casual observer.
- With enough eyeballs, all code bugs are shallow.
- As Eric Raymond observed, sheer numbers are an antidote for the complexity
and opaqueness of code. The more people who are looking, the more likely
you are to find someone who knows enough to see the cause.
- With any eyeballs at all, all doc bugs are obvious.
- Since documents are transparent, bugs are immediately discernable.
Typos and broken links can be spotted by anyone. Invalid content can
be identified by anyone who knows the product, or who attempts to follow
- Code changes have far_reaching consequences.
- Depending on the degree of modularity in the system, a change in one
place can have unforeseen consequences in other aspects of the
system. It is therefore necessary to keep track of changes, so you know
what caused things to break, and so you can undo the changes that caused the
- Documentation changes have no secondary effects.
- Even if documentation is horrendously, totally wrong, it can have no
impact elsewhere in the system (with the possible exception of a broken
link, which is hardly a cause for alarm.) The product will not be broken
as a result of the change, nor will user programs be in danger of failure.
The doc bug may be unfortunate, but it has no real impact on other areas
of the system.
- Code is the product
- The code will be run. If it has a problem, it will not run properly. Code bugs are therefore very expensive, and must be prevented.
- Documentation is information about the product
- Documentation provides information about how to use the product. In the infinitely remote worst cases, it could provide directions that make it impossible to use the product. But in that case, as well as all lesser cases, email lists, FAQs, forums, blogs, technical support, and word of mouth provide a remedy until the docs are fixed. Only the worst doc bugs rise to the level of minor code bugs.
- All changes in a set must be backed out at one time.
- If you made a change to 3 class files, undoing the change
requires undoing all 3 changes. Undoing only two or one of them is virtually
guaranteed to fail. It is therefore vital to identify all changes that
were made as part of a set--especially due to the possibility of unforeseen
- Changes can be backed out one by one.
- If changes are made to three different documentation files, nothing
absolutely requires them to be backed out together. One could
be changed today, another next week, and the third a month after that.
While perhaps not ideal, there are no significant penalties for making
changes in that fashion.
- Code bugs feed into Quality Assurance.
- Every bug found in the system is an opportunity for adding an additional
entry to the test suite--a suite which, by virtue of being automated,
can be run as often as needed to prevent regressions.
- Doc bugs are not handled by Quality Assurance.
- There are no automated tests for docs, no automated way to prevent
regressions. So doc bugs provide none of the salutary benefits that
code bugs deliver, in that respect. (But docs are transparent, and easily
corrected, so "regressions" are much less of an issue in any case.)
- Code bugs almost always track important information.
- Because code is opaque, the reason for unexpected behavior is typically
unknown at the outset. The bug report makes a good place to discuss
theories and devise isolation-tests. Once the problem is identified,
there are typically multiple ways to solve the problem. The bug report
provides a place to discuss those options and record the eventual selection.
- Doc bugs rarely track important information
- Documentation is transparent. When something is wrong, there is little
if any doubt as to what the problem is. There are no tests to devise,
and no options to discuss. There are rare exceptions, in which
case a bug report can play a useful role, but, typically,
a writer talks to a content expert, gets the necessary information,
and writes up the changes.
- Code bugs are a tiny part of the engineering process.
- An engineer opens the bug and may even carry on a conversation within
the context of the bug. But most the engineer's time is spent examining
code to find the source of the problem, creating unit tests, fixing
the code, and running the tests. Then the bug is closed. The time spent
working with the bug report is a fraction of the time that is spent
fixing the problem.
- Doc bugs can be a huge part of the writing process.
- The time spent processing a bug report and doing a workspace push
can dwarf the time needed to make a change--especially when the bug
report identifies a broken link or a typo. The work-to-reporting ratio
for a writer is therefore the inverse of what it is for an engineer.
- An engineer tends to work on one bug at a time.
- Within any given workspace, it is almost always the case that an
engineer will work on exactly one bug at a time. (If there are delays
in the approval process, a second workspace may be created to work
with another bug, but that workspace will also deal with only one bug
at a time.)
- A writer can, and should, work on many bugs at once.
- If a document has a broken link, a typo, and a suggested revision,
common sense suggests that all three changes should be made at one
time. But the efficiency of that process is offset by the need to separately
open and close three different bugs, which further magnifies the inverse work-to-reporting ratio.
- Code bugs can help engineers manage their workflow.
- A code bug can require a collection of synchronized changes in multiple
files. The bug report can be used to identify the changes that have
to be made, and act as checklist when the changes are implemented.
- Doc bugs do not help writers manage their workflow.
- For writers, the bugs-to-file ratio is inverted. One file may have
many bugs. To work efficiently, the writer needs a list of all bugs
against a given document, or in a given directory, sorted by document.
But no extant bug tracking system has categories that are useful for
- Code bugs identify modules, using categories.
- When a problem occurs, it is typically possible to identify the subsystem
in which the error occurs, but the specific file or files that cause
the problems, much less the lines in those files that need to be fixed.
Investigation is required to make that assessment, and the result of
that evaluation is recorded in the bug report before taking the next
- Doc bugs identify files, categories of little help.
- Because docs are transparent, bug reports identify a specific file,
and typically a specific line in that file. But the category depth that
is sufficient for code is of little or no help at all for docs. Because
docs indentify specific files, the categories should be of unlimited
depth. They could then duplicate the file's path, making it possible
to sort for all bugs that pertain to a specific file, directory, or product. Absent that capability, bug categories provide little or no value for writers.