Introduction
We (the people at my company XCESS expertise center b.v.) use DotNetNuke (DNN) for almost 8 years now, mostly for developing custom web applications. A long time I was puzzled by the fact that DNN had a large codebase, but very limited documentation for developers to orientate themselves to reuse the existing DNN code. In other words, use the DNN API.
About 3 years back, I stopped wondering and spend time to create a solution, resulting in a project on CodePlex: the DotNetNuke Developers Help File. This way, I shared our efforts with the DNN community.
What is the MSDN style DNN API help file?
This MSDN style based Windows help file did fill a gap for serious developers, developers (re)using the DNN API: more than 8.500 downloads of this help file for various versions of DNN in the past 4 years with 4 and 5 star ratings by people visiting this CodePlex project. For me: a success in sharing my knowledge and efforts in the community.
I blogged a couple of times in the past years about updates (see my blog history on www.dotnetnuke.com for MSDN Style help files for DNN), and got positive responses on most of my blogs.
DNN teams
Being the DNN team lead for the Events module for more than 4 years, I am, as volunteer, part of the DNN core team. Some time ago, I also volunteered for the DNN Reference Team with a high level goal in mind: the Reference Team drives to expand and enhance the foundation of knowledge available to all DotNetNuke stakeholders; developers, administrators, users, decision makers, etc.
Goals are good, but sometimes you have to start at the bottom. And so we did.
One of my personal objectives was to make the creation of the MSDN style windows based help file become part of a release of DNN: no separate project on CodePlex that I have to manage. The help and documentation should be an integral part of a DNN release (and it will save me time if DotNetNuke does it during a normal release process).
MSDN style help for the DNN API file: it is here!
With the release of DNN 5.6 one of my objectives as member of the DNN team was achieved: the MSDN style help file is now an integral part of the DNN release, see this link for the latest version of the help file related to DNN 5.6.1: http://dotnetnuke.codeplex.com/releases/view/59419.
DNN Corp (Philip Beadle) integrated the MS Build structure I developed for generating the API help file into the release build process of a DNN release. Creating a MSDN style help file does take some work, especially because you have to install additional software (SandCastle help file builder) to extract documentation from the codebase and generate a help file.
What has been achieved?
The DNN API documentation has grown tremendously over the last years.
When I started to create the MSDN style help file 3 years back (the help files for DNN 4.8.4), the resulting Windows help (.chm) file was about 10Mb in size. For the current DNN 5.6, the help file has grown from 10Mb to almost 30Mb!
The documentation grew, because DNN developers, including the DNN Corp. employees/developers, spend more time on putting structured documentation right into the (new and enhanced) source code. The community benefits from the work of the employees of DNN Corp!
Working on better documentation
But it was not only DNN Corp. developers who documented source code. Also, in the DNN Reference team, I assigned myself tasks to improve the existing documentation (or should I say: create the missing documentation). If you want to improve things to a certain level, it is good to have an example what that level should be. So I used one of the main base classes of the DNN (PortalInfo.vb) to create the standard for source code documentation.
If you have a look at an “old” version of the MSDN style help file (See figure 2 for a screenshot of the original documentation), you will find meagre and missing documentation in the entry PortalInfo Class at the main entry DotNetNuke.Entities.Portals.
Documentation is missing (the red text) and for the rest it is mostly only the automatically generated docs that are available, not much additional code comments have been added by the original developers of de code.
The improvement of PortalInfo.vb
I spend quite some time to create a standard how we would the API documentation to be: a well-documented class, methods and properties. And, if possible, examples how to use that part of the API. As mentioned, I used PortalInfo class as THE example, you can find the source of this class in the folder ~\Solution\Library\Entities\Portal\PortalInfo.vb of the source pack of DNN.
If you have a look at the same PortalInfo Class documentation in the newly generated MSDN Style help file of DNN 5.6 (See Figure 3 and compare it with figure 2), you will find an abundance of new API documentation, well ordered, structured, including see also, examples of use and more.
Help file and intellisense both improved
If you compare the sources of PortalInfo.vb of DNN 5.6 with e.g. DNN 5.0, you will see that all the info for the MSDN Style help file can be found as comment lines in the source code of PortalInfo.vb. This way, the documentation will not only be part of the (separate) MSDN style help file, it will also be part of intellisense in Visual Studio, if you are developing against DNN 5.6. The intellisense is contained within the XML documentation files that are (since DNN 5.2.0) distributed as part of a DNN release.
So my effort for documentation multiplies itself: both into the .chm MSDN style help file as well as into the intellisense in Visual Studio.
Everybody has access to the source code
Since all elements of the API documentation are retrieved from the source code comments automatically, downloading and unzipping the DNN source code pack is the first step to start working on documentation. The DNN source is wonderful study material for any .NET developer wanting to learn more about advanced .NET programming.
Choose anything you want to learn about
The current MSDN style .CHM help file is a great starting point for getting an idea about the wealth of the DNN API. If you start clicking around and reading bits, you will stumble upon parts (methods, properties, etc.), that are not documented to the level that you expect or want.
Now it is time to really start learning!
Have a look at your unzipped source pack and find the .vb source file that contains the class, methods or property you are interested in. This is a great way to learn about the structure of the whole DNN solution as well.
Document your learning
While you have opened the .vb source file in your Visual Studio and start learning: why not document the things you are learning about? A very good way to learn about things is to write about it. Use the standard VB.NET code comment tags. Just type 3 quotes on the appropriate place and the base comment structure will be generated by Visual Studio for you. Couldn’t be easier.
In PortalInfo.vb you can find reference samples of the code comments, see Figure 4.
A remark I want to make here is the attribute lang=”vbnet” in the code sample. Since the documentation compiler (MS) has a default of C#, this will signal the doc compiler to treat this as VB.NET sample code and apply the appropriate formatting.
If you do more than a single line of code documentation, you may want to consider installing the program GhostDoc (see http://submain.com/products/ghostdoc.aspx), which is a nice (free) Visual Studio Add In that helps to create structured code comments even better than the default Visual Studio way.
Share your efforts
DotNetNuke = Open Source = Community = Sharing
Although this blog talks about DNN 5.4.3, the procedure it is not linked to any specific version of DNN. It takes a little time to set it up, but it works like charm. The basics of this procedure is that you create a difference (patch) file with your additions to the code in such a way, that it can be implemented easily by DNN core developers.
If you share your efforts I am sure that your contribution (you) will get a recognition from the community! If you are willing to learn a lot, document your learning in the .vb code, why not become a member of a DNN team? There is no better way to have your learning experiences multiplied 800.000 fold.
