The Documentation Missing Link

subtext, process comments edit

I’ve been working on several different projects where I’m learning new stuff from scratch.  For example, I’m trying to write my own Subtext skin for my blog.  And as I read the documentation (or attend the meeting, or watch the presentation, etc.) that was created to convey the information to me, I realize that the creator of the material has always omitted the one thing that would suddenly allow the concept to click:


Picking on the Subtext skinning (since it’s fresh in my mind): It might be super important to tell me which lines in file XYZ need to be changed to show me how to make it do something interesting, but if you don’t tell me what file XYZ is and what its purpose is, the only thing I’m going to learn is that if you do this specific change, you’ll get this specific result.  I don’t have any context for why you made that change, so I can’t really infer any other changes that I could potentially make.  All I learned was the example.

I had a friend who would explain game rules this way.  If she was trying to explain, say, Monopoly, rather than starting out with explaining how the pieces move or what the object of the game is, she’d start out right in the middle with something like how you get sent to jail and how you get out, or what happens to you if you roll doubles.  If you already know how to play and need a refresher, that’s one thing, but for the new person you’re trying to explain the game to, you’re forgetting to provide context.

I see this happen a lot with folks who work on projects for a long time.  When it’s time to demo the end result of the project, they jump right in at the middle, forgetting to explain the overall value of the project, why the audience should care, or what the audience is about to see.  The problem there is that the audience will more than likely just nod their heads and tell you that they understand when the truth is they don’t.  Why didn’t they get it?  No context.

So here’s my public request to anyone trying to convey any information to anyone anywhere - provide context.  Your audience will thank you.