I got a couple of questions on our use of XML for the documentation so I’ll try to respond as best I can.  More to follow in another post.

 

Yes—there are XML developer code comments within the .NET code.  No—those developer comments don’t go directly into the documentation.  With a few notable exceptions, most developers are not trained writers. :-)  However, those developer comments are used by the programmer writers to help them write the reference pages for those API’s.  Our reflection system pulls out the XML code comments and puts them into the templates that the writers use.  The writers then “clean them up” as needed and add more context, code snippets and other information.

 

Why not have the writers put the “real” text into the XML code comments?  It’s just too hard to manage that.  You want to keep strict track of what happens in code files; having the writers party on the code files creates more churn to manage.  Technical documentation also tends to happen later in the development cycles—and continues well after the code gets “locked down”.

 

A Note on Auto-generated reference pages

 

The automatically generated reference pages are meant to be place holders until the programmer writers can fill in more descriptions and details about the API’s.  We have a lot of ambitious goals around code snippets in those reference pages.  Ideally, we’d have some kind of code snippet in every reference page (you will be able to filter the code snippets by language).  We’ve got a long way to go to get there.  Our current “authored” content coverage is pretty slim.  But the alternative is to only include authored ref pages—we think it’s better to at least include the place holder pages for now.