Microsoft's effort to document protocols for DOJ hits a snag

The challenge continues for Microsoft to produce documentation about Windows' communications protocols that others outside the company can understand. Two weeks ago, the Justice Dept.'s team started making its own suggestions.

According to the US Dept. of Justice's regular Joint Status Report on the ongoing effort by Microsoft to meet the commitments of its settlement with the government, the Technical Committee (TC) overseeing the project for documenting communications protocols has not been entirely pleased with the quality of Microsoft's work thus far. It's not that Microsoft hasn't produced papers -- it has, and perhaps now that the count has reached the five-digit mark, parties may have stopped counting. It's that the work has been hard to understand, and now the TC is trying to help Microsoft by suggesting a new set of documentation templates based on what it considers to be approved industry standards.

But apparently Microsoft tried to comply, or maybe make some compromise that blended its own methods with the TC's. The result, according to the report, isn't yet satisfactory; and now, the company faces a new problem: While documenting the existing protocols, a new set of protocols has been accelerated for the Windows 7 project, and Microsoft must document those too.

"At Plaintiffs' request, Microsoft agreed to create a set of additional 'system' documents that would provide more detailed information on the interaction between the protocols in a number of complex scenarios," reads one section of last Friday's report (PDF available here). "Microsoft began the project by creating a template to govern preparation of the system documents; Microsoft also created three pilot system documents using the proposed template in an effort to demonstrate the suitability of its template despite the TC's initial concerns. The TC's review of the pilot documents reinforced its concerns with the suitability of the template. Microsoft revised the template based on the TC's feedback and informed the Court in the prior Joint Status Report that, subject to finalization of the templates with the TC, Microsoft planned to publish drafts of all nineteen system documents by the end of March 2009 and to publish the final version of all system documents by the end of June 2009."

Microsoft created a second template, according to the Report, but apparently they only served to further demonstrate the problems the TC was having. So two weeks ago, the TC gave Microsoft a new template to work from, most likely with a directive to start over.

"Plaintiffs and the TC are mindful of the challenges to creating system documents in the circumstances presented here. Therefore, the TC templates adapt recognized software engineering practices and well-known documentation models to this project," reads the Status Report.

Anyone who's worked with Microsoft official documentation for any period of time over the past few decades knows how difficult it can be to interpret, although the company has improved significantly (in my opinion) in recent years.

In the documentation publishing business, templates are not just pieces of software that govern the placement and formatting of style elements. They're principles that govern how topics are approached -- or, to say in active voice, how you approach a topic. There are frankly any number of sets of "industry accepted principles" for documentation, and frankly, a lot of them contradict one another. For example, when you do write in active voice, are you writing for "the user" (as in, "when the user clicks this button, a dialog box will be displayed") or for "you" ("when you click on this button, you'll see a dialog box")? Do you use future tense ("a dialog box will be displayed") or present ("is displayed")? And if you start out in active voice, must you stay that way all the time ("a dialog box displays")?

These are aspects of consistency which govern the way documentation is produced, and those are only surface-level examples. Another major problem authors often have is remembering whom they're writing for, or maintaining the same target reader throughout a document. Many Microsoft internal documents, for example, have been written for the developer who may be working with technology in building something, and you might think this is precisely the person who needs this documentation most.

But the evaluators of this documentation -- as we learned in the case with Microsoft's attempt at compliance with European Commission directives -- are not developers themselves; and even when they hire mediators or consultants such as the DOJ's TC, oftentimes they've only served to outline the gap between what the developer needs to know and what an outside observer needs to know.

Such discrepancies are actually not new, and are not limited to Microsoft. This is why some companies are adopting the approach of publishing multiple segments for different readers -- partly for a developer, partly for a non-developer. This may be what Microsoft is being asked to do (BetaNews has contacted Microsoft for further information), and if that's the case, this could be a major burden for anyone.

The reason why this is important is this: We know for a fact that there will be a new Justice Department come next January; and regardless of which presidential candidate wins the election, the likelihood that the new Antitrust Division will set the bar higher for compliance, is very high. If Microsoft's efforts to comply with DOJ directives for disclosing interpretable information about communications protocols is deemed -- as it was in Europe -- a failure, that could negatively impact the company's ability to produce Windows 7 -- whose communications protocols the company is acknowledging will be somewhat different -- next year, on schedule.