I had the absolute pleasure of attending the Write The Docs conference in Portland last week. Write the Docs is “a time and a place for this community of documentarians to share information, discuss ideas, and work together to improve the art and science of documentation.” It was one of the best conferences I have ever attended, with interesting presenters and people across the board. A crazy compendium of notes and links on talks and presenters is here.
The top three talks I saw were:
Brian Troutwine’s talk on instrumentation and complex systems is something that anyone who manages a real-time (e.g. AVL, SCADA, etc.) system should watch. He begins with pointing out that complex systems fiendishly difficult to communicate about. This gap of understanding is difficult to bridge in documentation. Instrumentation combined with documentation is really where the magic happens, and where you see the system actually work.
If you don’t know how the system should behave, you can’t say how it shouldn’t.
IF YOU DON’T TRUST A COMPUTER BECAUSE SOMETIMES IT DOESN’T TELL YOU THE TRUTH, TELLING IT TO TELL YOU TO TRUST IT IS ASKING IT TO LIE TO YOU SOMETIMES.
Maxwell Hoffman’s talk on writing for a global audience fit the theme well. He points out that by following
10 rules from standardized aerospace engineering English, our writing can not only be more clear, but better understood in translation. Sadly, the video is not available but notes are.
Millenials are re-incarnated people who died in 60s. They use active voices.
Finally, Christina Elmore’s talk on Death by Documentation takes a hard line on the difference between presentation and documentation, and meetings versus conversation. In it, she references two great (and free!) resources: Nancy Duarte’s Resonance Book, and An Introverts Guide to Better Presentations.
Work to eliminate the presentation within your organization.