Reference documentation provides comprehensive information about the programming elements that are associated with technologies such as ASP.NET or Windows Presentation Foundation, or programming languages such as C++, C#, or Visual Basic. Reference topics are typically used to document class libraries, object models, and programming language constructs.
Note
Information such as configuration schemas, compiler options, and error messages might also be documented in reference topics, and will not necessarily follow the guidelines described in this section.
Software developers consult reference documentation to look up specific programming elements, not to read about programming concepts or product features. Developers often compare programming elements to determine how they relate and to decide which one to use for a particular scenario.
Therefore, standardization and consistency are essential in helping users get the information they need as quickly as possible. If your reference topics use a standard topic design, predictable headings and structure, and consistent wording, users will know what to look for and where to find it on the page.
Generally, reference topics are titled by using the name of a programming element (such as Clear), followed by an element type (such as Class, Method, Property, or Event). If the name is shared by multiple elements, you can add a differentiator such as the parent element name or the product or technology name. The differentiators are especially important if your content coexists with other reference documentation in a large content repository such as the Microsoft Developer Network (MSDN) Library.
Microsoft style for reference topic titles
Clear Method
Device.Clear Method
Clear Method (Microsoft Ajax)
Not Microsoft style for reference topic titles
Clear
The following table lists the information that is typically provided in reference topics. Not all sections will appear in all topics. For example, the “Property value” or “Field value” section appears only in reference topics for properties. Sections will also vary, depending on the language, product, or technology being documented.
Some of this information, such as syntax, parameter names and types, and return values and types, can sometimes be generated directly from the source code of the technology that is being documented. Some organizations also export code comments from the source code and use that information to fill in sections, such as the programming element description, parameter descriptions, and remarks. If you decide to auto-generate your reference documentation from code comments, be sure to review the quality and appropriateness of the comments. Code developers might leave out details that seem obvious to them but that might not be obvious to users. In addition, developers use comments to provide implementation or internal details, to flag areas that might change, and to document aspects of the code for maintenance purposes. This information might be useful to other internal code developers, but it might not be suitable for user documentation.
For examples of technical reference topics, see the .NET Framework Class Library section (http://msdn.microsoft.com/en-us/library/gg145045.aspx) of the Microsoft Developer Network (MSDN) Library (http://msdn.microsoft.com/library/).