My cats abhor my new Dyson vacuum cleaner…

I need but pick it up to trigger fierce hissing and scurrying.  I, however, keep finding reasons to love it.

With every use it reminds me of the need and attendant procedures of cleaning its filter. Pop it open, carry it to the sink, and there again one finds embedded language agnostic instructions.

This represents subtle genius.  Users lose paper instruction manuals.  Online documentation is out-of-sight and out-of-mind.  Put it in plain sight, however, and you channel users toward the desired behavior.  Customer satisfaction goes up.  Support costs go down.  Everybody wins.

A few months ago I found myself overhauling the DevOps pipeline at Finite State.  To that end I crafted a DSL against which a code generator runs that stamps out the CloudFormation to instantiate a CodePipeline in AWS with everything you need either to generate a production system, a test system, or a fully realistic dev-int environment.

Usage is fairly simply and yet when a new engineer shows up things like this can prove quite mysterious.  What do to?  Exactly what an enterprising colleague of mine did totally reflexively without being asked: he created and homed detailed instructions in the README.md of our GitHub mono-repo so it’s the first thing any developer will bump into when arriving at our system.

Make it impossible for your users to be confused and do the wrong thing.  The dividends you will reap are enormous.