Good documentation is an important part of a successful product. Creating full and comprehensive description of functions and capabilities of a software product or component takes time and patience. In this article I will discuss some practical aspects of creating documentation for .NET components.
Let's assume that we have finished or almost finished creating a .NET developer library (developers are end users in this case). Library's API is perfect, the number of bugs impressively small, and indeed it is not a library, but simply a storehouse of perfect code. One little thing is left to do. We need to explain to users how to use this wonderful product.
There are different approaches to writing documentation. Some teams prefer to start producing documentation at the time of inception of the product. Others postpone writing manuals to a later time. In some teams there are people who go from developer to developer and from manager to manager asking questions and accumulating knowledge about the product. These people are responsible for writing documentation for the product. In many small teams there are no such people and the documentation is often written by a product developer or developers. Some teams use third-party tools like Help & Manual, which, as a full-fledged text processor, can be used to create documentation with a very complex layout of the pages. Such tools are also good for producing documentation in a variety of formats like PDF, CHM etc. Many people use a different approach, widely advocated in recent years - they write documentation directly in the code of the product.
I have used third-party tools and wrote documentation directly in the code. Tried to start writing documentation before and after development is done. In the end I decided for myself that it's better to postpone writing manuals to the second half of a product development cycle. The closer to completion the more stable the API, feature set etc., and less adjustments to the documentation will be needed. Writing documentation directly in the code eventually proved to be more convenient than using third-party tools, although at first it seemed quite the opposite. This article is just about how to write documentation directly in your code and what you can do with the written later.
Documenting the API
The C# and VB.NET compilers are able to recognize comments, decorated in a special way (XML comments) and, if necessary, create an XML file which can then be used to generate the documentation. In order to create documentation this way it's needed to describe all the public code entities (classes, interfaces, methods etc.) using XML comments. The XML comments start with three forward slashes. It looks like this:
/// <summary>
/// Gets the R component from ABGR value returned by
/// <see cref="O:BitMiracle.LibTiff.Classic.Tiff.ReadRGBAImage">ReadRGBAImage</see>.
/// </summary>
/// <param name="abgr">The ABGR value.</param>
/// <returns>The R component from ABGR value.</returns>
public static int GetR(int abgr)
{
return (abgr & 0xff);
}
Read more: Codeproject
Let's assume that we have finished or almost finished creating a .NET developer library (developers are end users in this case). Library's API is perfect, the number of bugs impressively small, and indeed it is not a library, but simply a storehouse of perfect code. One little thing is left to do. We need to explain to users how to use this wonderful product.
There are different approaches to writing documentation. Some teams prefer to start producing documentation at the time of inception of the product. Others postpone writing manuals to a later time. In some teams there are people who go from developer to developer and from manager to manager asking questions and accumulating knowledge about the product. These people are responsible for writing documentation for the product. In many small teams there are no such people and the documentation is often written by a product developer or developers. Some teams use third-party tools like Help & Manual, which, as a full-fledged text processor, can be used to create documentation with a very complex layout of the pages. Such tools are also good for producing documentation in a variety of formats like PDF, CHM etc. Many people use a different approach, widely advocated in recent years - they write documentation directly in the code of the product.
I have used third-party tools and wrote documentation directly in the code. Tried to start writing documentation before and after development is done. In the end I decided for myself that it's better to postpone writing manuals to the second half of a product development cycle. The closer to completion the more stable the API, feature set etc., and less adjustments to the documentation will be needed. Writing documentation directly in the code eventually proved to be more convenient than using third-party tools, although at first it seemed quite the opposite. This article is just about how to write documentation directly in your code and what you can do with the written later.
Documenting the API
The C# and VB.NET compilers are able to recognize comments, decorated in a special way (XML comments) and, if necessary, create an XML file which can then be used to generate the documentation. In order to create documentation this way it's needed to describe all the public code entities (classes, interfaces, methods etc.) using XML comments. The XML comments start with three forward slashes. It looks like this:
/// <summary>
/// Gets the R component from ABGR value returned by
/// <see cref="O:BitMiracle.LibTiff.Classic.Tiff.ReadRGBAImage">ReadRGBAImage</see>.
/// </summary>
/// <param name="abgr">The ABGR value.</param>
/// <returns>The R component from ABGR value.</returns>
public static int GetR(int abgr)
{
return (abgr & 0xff);
}
Read more: Codeproject