Documentation Laws

Just a collection of laws that exist on the internet.

Eshult’s Law of Documentation Distance

The farther away documentation is from the work it supports, the less likely it will be utilized and the faster it will become obsolete.

Ask yourself, which of the following items is more likely to be utilized and kept current:

• A comment line added in software code vs. a note in a separate document or wiki?
• A human-readable variable name vs. a variable definition in a document on a shared note page?
• A tool tip in a software dialog box vs. a help article on the software website?
• A knowledge base article served up with in-app searches vs. a search bar on the knowledge base site?

This law is not limited to software documentation:

• A work instruction posted on the machine in a factory vs. a work instruction in a binder on a shelf in the front office?

The proximity for utilization can be measured in units of time as well as electronic or physical distance:

• A software pop-up explaining a new feature the first time a user selects the feature vs. a training video of the new feature viewed three months before the user has need of it?

Source: https://medium.com/@woet_88989/eshults-law-of-documentation-distance-b4827fdf8cae

Arnold’s Laws of Documentation

1. If it should exist, it doesn’t.
2. If it does exist, it’s out of date.
3. Only documentation for useless programs transcends the first two laws.

Source: https://www.bookofthrees.com/arnolds-laws-of-documentation/

Sigberg’s Six Laws of Documentation

1. In order for someone to read a document they must first:
   • Know that it exists
   • Know where to find it
   • Care enough about the subject to actually take the time out of their life to look it up.
2. Derived from the first law: The odds that anyone will ever read a document are approaching zero.
3. Derived from the second law: People who are made aware of the existence of a document will still complain about its non-existance on a regular basis. Reminding them that it exists will not make them stop.
4. If by some fluke of the universe someone actually reads a document, they will always find that either:
   • it’s outdated
   • the information sought is not in it
   • or both (see addendum).
5. The number of pages in a document and the time spent writing it, is in perfect negative correlation with the likelihood of someone ever reading it.
6. Since no one ever reads documentation, it’s impossible to know whether something has been documented.

Addendum (Sigberg’s Paradox of Documentation)

The document states «complete» and «outdated» are one and the same, and the transition to both states are instantaneous. From this follows the paradox that a document will always be either up to date but incomplete or complete but out of date (and thus incomplete). As a consequence, finishing documentation is logically impossible. Thus, the inevitable end state of any document is to be out of date and incomplete.

Source: https://medium.com/@thorbjorn.sigberg/sigbergs-laws-of-documentation-fab155b2415b