Write the Docs: Scot Marvin – Wabi-Sabi Writing

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Scot covered how we can use wabi-sabi in our writing. He first started reading about wabi-sabi when his first child was born. He found the first rule of wabi-sabi seemed to be that you don’t talk about wabi-sabi. It has a respect for syntactic ambiguity which goes against much of our Western ideals. Essentially, though, it’s beauty in impermanence, imperfection, and incompleteness.

Our Hellenic ideals push us toward perfection, but ultimately we create very little of perfection. Wabi-sabi embraces the rustic and the simple. It allows for tranquility but also asymmetry. It’s not about being a Luddite. It’s also not complacency. Allowing for imperfection does not mean accepting the generic. You strive for excellence, not perfection.

Scot works in an agile software environment. Essentially agile means finding out where you are, taking small steps toward your goal, and then adjusting your understanding based on what learned. It, like wabi-sabi, is not about creating perfection. It’s a repeatable process that lets you improve and strive toward excellence.

He tries to abide by four suggestions in his writing.

  1. Less Faulkner, more Hemingway. They are the two extremes of America writing. Write in simple, clear sentences. Your documentation should be clear and concise.
  2. Less Coltrane, more Davis. Or, strive for tranquil writing. Miles Davis was known for his economical restraint when it comes to music. Scot strives to put support out of business with his restrained documentation.
  3. Less Versailles, more Ryōan-ji. Work toward simple writing. Your docs shouldn’t be the equivalent of the gardens at Versailles. This can also be thought of as the, “Don’t get too cute” principle.
  4. Done is beautiful. We can’t truly complete anything, but we can get it done. Incomplete, imperfect writing is okay. Incrementally make it better; don’t just wait for perfect completion.