Bit rot in the documentation

This week I’m attending Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. It’s a privilege to be here, and to speak at this cool get-together.

My session is called Bit Rot in the Docs. (The link goes to the slides on SlideShare.) The presentation looks at how documentation can degenerate over time, and some techniques for finding and fixing errors.

The very mention of bit rot will strike terror into an engineer’s heart. “Unused programs or features will often stop working after sufficient time has passed, even if ‘nothing has changed’.” (From the hacker’s Jargon File.)

Bit rot affects documentation too. Whether the cause be a changing environment, human error, or the infamous cosmic rays, we need to root out that rot. But should the technical writer read and test the documentation on a regular basis? That’s the least efficient and most error-prone way of detecting doc decay.

Instead, in this session we looked at the following techniques:

Automated testing of code samples.
Documentation reviews as a standard part of engineering team procedure.
Collaborative spot-testing.
Customer feedback.

For more details of the session, see the slides on SlideShare.