Duplex Documents

I spend the vast majority of my working day within the cosy confines of Visual Studio 2005 and SQL Server 2005 Management Studio, which is fortunate because I feel most at home with these tools. But occasionally I have to let other people know what I've been up to, which inevitably involves firing up Word and coding   in a much higher-level language - namely, English.

Unlike working in C#, where I only have to write in order to be understood by the   compiler, the documents I write in English frequently have to be interpreted by multiple humans who have differing levels of interest in the subject matter. Personally, I find this task more difficult than coding, so occasionally look to bloggers and favourite technical authors for inspiration regarding style and structure.

Case in point - last week I had to make a number of colleagues aware of wide-ranging changes that I have developed to a number of database schemas. How best to do this? Simply listing all the table changes doesn't serve to explain my motives and alienates business-oriented readers, but writing an explanatory narrative alone fails to go into sufficient detail for the technically-minded audience.

The answer?  Simply, a duplex document, consisting of both a summary narrative, followed by the detailed reference. I can't claim credit for this idea - I've recently been reading the thoroughly enjoyable xUnit Test Patterns: Refactoring Test Code, part of the Martin Fowler signature series which follows this very pattern (as does Fowler's own classic Patterns of Enterprise Application Architecture). In fact, Fowler has even documented this pattern of authorship over on his bliki.

So far, this approach seems to have worked well for my requirements - when writing my little document, I never worried that I was going into too much detail, or being too superficial, because I was actually writing two separate documents to meet both needs. And none of the recipients have yet got back to me for clarification or to complain about extraneous material.  Hurrah!