Tag Archives: documentation

Over communicating

I once had a college class where the instructor was in the process of writing a text book for the class. So we were being taught out of photocopies of the draft textbook. It wasn't a very good class.

It wasn't that he wasn't a good writer. He was. The previous semester I'd had a great class using one of his text books. But it was taught by a different professor. There were some places that the text made a lot of sense to me, and some places where the different approach of the non-author professor made far more sense. With two points of view it's about synthesizing an understanding. If something from the book didn't really stick, something from in class might. And each aha moment made everything you'd read or heard before make a bit more sense.

I was reminded of this this morning reading through some technical documentation that was light on content and heavy on references. It was written that way so as to not repeat itself (oh, this part is explained over her instead). And while that may make sense to the authors, it doesn't make for an easy on ramp for people trying to learn.

It's fine to over communicate. It's good to say the same thing a few different ways over the course of a document, and even be repetitive at times. Because human brains aren't disk drives, we don't fully load everything into working memory, and then we're there. We pick up small bits of understanding in every pass. We slowly build a mental approximation of what's there. And people have different experiences that resonate with them, and that make more sense to them.

There isn't one true way to explain topics. So, when in doubt, over communicate.