Udostępnij za pośrednictwem

A response to criticism for Microsoft's compliance documentation

  • Artykuł

I want to preface this that this post is my personal perspective and that of what I have seen from my peers and is not anything official from Microsoft.  Anyways...

I just encountered an article on Slashdot chastising Microsoft's documentation indirectly by citing a ruling that Microsoft's documentation is unfit for US consumption.  As a writer who produces our documentation I'm a little offended but I also understand the typical criticisms.  For developers, documentation can be a giant pain in the tush...  The last thing that you want to be working on after writing some cool code is to go back over it again and explain it so that someone else can use it without having your domain knowledge.  For architects, it is difficult to specify a particular protocol or technology without revealing trade secrets.  For programming writers (what I do) it can be difficult to determine which things are important for developers, which areas they're going to have trouble with, and the best way to communicate this (are we dealing with expert programmers, or novice programmers?):

More information here: https://ploneglenn.blogspot.com/2008/09/bane-of-every-coder.html
And here as well:  https://www.dynamicalsoftware.com/cgi-bin/ViewBlogEntry.pl?id=14

The challenges that Microsoft faces in producing compliance documentation for software are varied.  For starters, what is sufficient documentation, and for whom?  For an architect, a specification that shows the system from a high level and that specifies the protocols for a particular technology may be sufficient to communicate a means for implementing a custom or third party application that uses or interoperates with a technology.  For SOME developers (and some interfaces for that matter), code demonstrating how an API is used is sufficient to use that API.  For others, a broad explanation of the particulars of that interface and its usage are necessary.  What if our audience is NOT a developer?  What is sufficient for those people?  Do we need to explain what a computer is, what networking is, and so on?  Where do we, as writers draw the line?  How do we identify the right areas to focus our attention.  The even larger problem is that we are constantly working with a moving target.  The documentation MUST ship for compliance at the same time that its related product is shipping.  If halfway through the product's development lifecycle, the interfaces change, all of the work that we, as writers, have produced can immediately become useless.  Another problem is that if a particular design will not work, the architecture can change, eliminating much of the writing work that was performed to explain the architecture.  These are the problems that face writers every day.

What the article stating the our docs are unfit for consumption focuses on is the issues around documentation compliance for Microsoft's protocols.  The article doesn't say, "it's hard to produce software using Microsoft's platforms", it instead is saying "it's difficult to interoperate with Microsoft's ecosystem without using Microsoft's platform".  This is the difference between the platform documentation that we produce and the compliance documentation.  The compliance documentation SHOULD exist so that other people can use our protocols to easily deliver alternative implementations of what we've done.  This IS pretty easy for us to deliver because at some point, we designed the product (horray for Architects) and then described the product to the developer audience (go Program Manages!) and the implemented the design (developers, developers, developers).  The only problem is, for compliance, our existing documents simply will not do.  There is a specific format that we need to deliver to the EU.  There is a specific format that we need to deliver to the DOJ.  And these formats are entirely arbitrary.  Whether or not that document format works for our engineering process or not, we need to deliver our docs to them in it.  From our perspective, compliance documentation is a long set of hoops that regulatory bodies are making us go through in order to squeeze money out of us.  The specifications that we receive for formats that we'll be delivering documentation are legal documents that are filled with confusing and unspecific requirements. 

Anyways, I think I'll pick away at a few points in the article:

>consistently had trouble with producing complete and useful documentation
Now, this is a very pointed statement.  Microsoft has consistently had trouble producing complete and useful documentation.  What is complete documentation?  This is defined differently by the EU and the DOJ.  Compliance is a very tricky situation.  Ask the developers, program managers, and writers who were working on the protocol compliance documentation that we produced for the EU.  They gave us a specification that indicated we needed to deliver them documentation in some arcane format (I'm not sure exaclty what it was, but it was something along the lines of delivering docs on microfilm).  Another issue is that there is no set of documentation that is perfect for every audience.  In the case of what we were delivering to the EU, I'd imagine that the audience was lawyers, writers, and industry experts.  The case that Microsoft's documentation is insufficient is most typically that you can't debug into our sources as you can with OSS.  If you're comparing closed source software to open source software from a debugging perspective, it's certainly easier to determine WHY something doesn't work in the open source case.  Software ships with bugs, and if these bugs are in protected bits of code, you can't see why something is broken.  In closed source software, we need to design assuming that our users will NOT be able to debug into all of our sources.  As a result, we have to future proof our designs for debugging with the sources that we give - this is difficult for architects and program managers.  Additionally, developers have to be excruciatingly careful when producing code so that meaningful messages are returned to third party developers.  With aggressive product cycles, sometimes the due diligence is overlooked, and Microsoft does a good job in preventing this with internal processes and quality standards.  Nobody's perfect, but in my opinion, we are doing a pretty darn good job in addressing these two issues for developers.

Later, the article goes to say...

>Most developers find Microsoft's API documentation to be pretty good ... the company can produce similar documents when it is determined to.
*sigh* It's relieving to know that there's the perception that we're doing something right.  This is the documentation that my peers and I focus our efforts on.  The difference between this documentation and the compliance documentation is that we're able to plan around this.  The compliance stuff tends to "come up" when we are not in compliance.  As a result, the resources that we typically have when producing documenation are gone working on new projects, or have left the company.  In turn, we, as writers, have to reverse engineer the code to work out the various aspecsts of compliance to try and meet the needs of various regulating bodies.

Anyways, compliance is a huge pain for Microsoft.  If you're a dev for a small company, be happy you don't have to handle it all the time, but it also is a good idea to think about documentation to future-proof your code from being a headache if it ever becomes subject to compliance work.

Comments