Share via

Build Information and Verbosity from Whiteboard to Publication

  • Article

Often when I write, I’m communicating about a subject in which I already have fairly thorough knowledge. For example, when I’m sharing basic technical information with a co-worker via email. Or producing a status report. Or simply writing a topic about a subject in which I’m fluent. The fingers fly easily over the keyboard without pause. Quick, easy, mundane. On the other hand, exploratory writing, that kind which is truly creative, can be much more exciting, fun, and sometimes terrifying. This kind of writing is an exploration into the unknown.

For an endeavor to count as an exploration, you can’t know exactly where you are going or what you will see until you get there. Even so, you are motivated by a strong hunch that there is fruitful territory “out there somewhere.” A true embodiment of the mysterious cone of uncertainty, at the beginning of such a journey you have very little confidence in your estimate of how long the work will take. As you strike out toward the tempting pool of water in the distance, sometimes you feel tremendous hope about the outcome, and sometimes you begin to fear you are approaching a mirage. One might easily assume that technical writers don’t get to have this kind of adventure. But I think many in our business would agree that we get to face both the delight and the discomfort of an empty page that has an uncertain future. Sometimes the journey requires us to foray into the realm of visual information, one that we verbal folks sometimes find a bit daunting in and of itself.

Take “Manage Build Information and Control Verbosity,” which I published last week. My initial goal was to simply tease out and clarify the key pieces of information needed to develop a build process that does not overload your system or your users with information.  The main piece was a fairly simple table that articulates the effect of each possible verbosity setting. I already had this table written, so the topic should have been fairly short and sweet to produce.  But there were a few loose threads I noticed that left questions in my mind. To follow one of them, I met briefly with one of the developers and drew a rough sketch on the whiteboard:

The sketch was not complete (and the handwriting was horrible!), and yet it also ventured outside the initial scope I planned for this topic. Even so, had an intuition that this larger context might be somehow helpful to customers, especially those new to our product. So I decided to invest more time and pressed on with more research, after which I developed this rough Visio draft for our artist:

While my optimism about the potential value of the outcome was increasing, I was a little worried about whether a reasonably complete and fully accurate diagram would fit into the MDSN format. I met in person with our artist and she showed a surprising and wonderfully cheerful attitude about helping me tame this beast. She sent me this draft:

This was a great first production draft, but there were lots of changes still needed, which I documented in OneNote, as you can see above. As I marked up the changes, I could see that this vision was looking more like a pool of water and less like a mirage as it came into sharper focus.

The end result:

You’ll notice in this final version of the image that I’ve begun to leverage some personas (Julia and Roberto) that I set up for our team a few months ago. At some point in the future I may blog a bit more about them.  Regardless, you can expect to see a lot more of these people in action, working through what I hope will be realistic and illustrative examples.

I hope the investment in the image proves to be worth the cost in terms of value to customers. But of course its ultimate success, and that of the topic (Manage Build Information and Control Verbosity) depends not on what I think, but on what you think. So in closing, as I often say, I look forward to hearing your feedback!

Andy

Comments

  • Anonymous
    June 05, 2011
    Thanks for the investment in making this diagram. As for the Personas (Julia and Roberto) I'd love to see them written up to better understand the tooling focus. Similiar to what the test team did here: msdn.microsoft.com/.../bb414765.aspx