Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

While browsing the MSDN documentation for the .NET Framework Class Library (FCL) I've always been amazed by how consistent and fully documented it is. It's a constant companion when developing .NET applications. Most doubts that arise when using the APIs are covered. The contrast with e.g. the older Win32 documentation is striking.

Some examples:

  • Documentation for properties always starts out with either "Gets" or "Gets or sets" to specify accessors.
  • Type parameters start out with: "The type of ...".

Does Microsoft use a documentation convention which is followed for the FCL? If so, is this convention publicly available for me to use as well?

share|improve this question
    
Microsoft publishes the standard for all Microsoft .NET languages. –  Ramhound May 14 '12 at 16:09
    
@Ramhound: In this case, the standard applies to the language only, not the documentation. –  Steve Evers May 14 '12 at 16:39
1  
To address a few issues: Documentation questions are on-topic here on Programmers. Questions about where to obtain specific style guidelines are also on-topic, if they don't appear to be readily available (meaning by a couple of quick searches using your favorite search engine). It's also clear that some languages provide style guidelines for in-code documentation. I don't see any problems with this question at all. –  Thomas Owens May 14 '12 at 16:46
1  
The closest I found is a brief example within the subtopics of msdn.microsoft.com/en-us/library/b2s063f7.aspx (specifically msdn.microsoft.com/en-us/library/z04awywx.aspx). –  Danny Varod May 14 '12 at 17:11
2  
Looking at the .net documentation I'm always amazed how they manage to put so much boilerplate and so little substance in there. IMO the Win32 API documentation is much better that the .net documentation. –  CodesInChaos May 14 '12 at 22:09

1 Answer 1

Yes. There is a spec of sorts. That spec is built into StyleCop.

What it basically does is turn "style" errors (comments, code layout/formatting etc.) into build errors.

You can also include/exclude any rule that you like.

share|improve this answer
1  
Doesn't answer the question - the question is regarding the structure/wording of the text within the documentation. –  Danny Varod May 14 '12 at 17:08
1  
@DannyVarod: Yes it does. eg: blogs.msdn.com/b/sourceanalysis/archive/2009/08/11/… note that stylecop and fxcop are different in that regard. –  Steve Evers May 14 '12 at 17:37
1  
+1 My mistake, I was indeed thinking of fxcop. –  Danny Varod May 15 '12 at 4:49

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.