Three Great Talks from Write The Docs

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 dif­fi­cult to com­mu­ni­cate about. This gap of under­stand­ing is dif­fi­cult to bridge in doc­u­men­ta­tion. 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 elim­i­nate the pre­sen­ta­tion within your orga­ni­za­tion.

Introduction

My name is Tony and I’ve spent most of my career putting GPS on buses.

This blog exists to introduce transit people to technology, and tech people to transit. I will cover a breadth of topics, from the philosophical, to practical, to deeply technical.

I believe in sharing my experience in a clear, concise, accessible, and vendor-neutral (no sales pitches!) manner.

I will be happy if this blog is a fraction as helpful to the industry as Jarrett Walker’s Human Transit blog.

FAQs are below the fold.
Continue reading “Introduction”