I have a hard time interviewing people.  No, it’s not because I don’t enjoy being a complete asshole or because I don’t know about the perfect interview question.  It has everything to do with the fact that I’m a fatally honest son-of-a-bitch.  So, when someone comes into an interview for a developer position at my company and asks what methodology we use, I always answer, “We don’t.”  It’s not that we’re completely disorganized (although sometimes we’re close), it’s that we are extremely production-oriented, and since we’re not a software company, our executives could care less about Kanbans, Scrums, and Waterfalls.  I’m not excusing this.  I think it’s a crime that we aren’t following something.  But it’s the reality of the situation and it’s going to take a long time to change.

One of the biggest problems any haphazard development department like mine encounters is a total lack of documentation.  It’s a cliché that developers hate documentation.  Especially project documentation.  I’m not even sure developers should be responsible for project documentation.  However, following these simple steps, I have found that I almost enjoy documenting my large libraries and frameworks, making life easier on my peers as well as satisfying auditors, PMs, and other business riff-raff.

Note: The following has a “tutorial” feel to it.  Both Sandcastle and GhostDoc are so easy to use that if you don’t want to follow these steps as guidelines for best-practices, then just go get them and start using them.

1. If you’re not already, get familiar with Visual Studio’s built-in XML documentation capabilities.  In C#, type “///” (‘’’ in VB) above a class, method, property, namespace, whatever.  You’ll see a nice set of comments fill in for you:

   			/// <summary>
   	

   			/// A method that does stuff.
   	

   			/// </summary>
   	

   			/// <param name="stuff">A <see cref="IDictionary{TKey,TValue}" /> that has stuff in it.</param>
   	

   			private static void DoStuff(IDictionary<string, int> stuff)
   	

   This is a well-known feature of VS, so I’m not going to spend a great deal of time on it.
2. Use very descriptive names for everything!  I could give a crap if you name a property “ContainerForAccountInformationThatHasAReallyLongName.”  At least I have some idea what the property is.
3. Download and install SubMain’s GhostDoc.  Let it integrate with Visual Studio as it installs.  Don’t be afraid, it’s probably smarter than you are, and it’s free.  Once you have it installed, open up your favorite project and find a class or member with a really nice signature.  Something with a lot of parameters, generic type parameters, etc., and make sure everything is following item 2.  Put your cursor on the member signature, right-click (or use the built-in hotkey) and select “Document This.”
   
   GhostDoc extends the built-in XML documentation and interprets not only your member and parameter names, but what the description text should possibly be.  And if you are naming things well, it’s usually pretty damn close to right.  It is quite configurable and even attempts to interpret situations where you should add remarks along with summary documentation.  Using GhostDoc has greatly decreased the amount of typing I do for inline XML documentation.  Here’s an example of a method documented by GhostDoc with no changes made:

   		/// <summary>
   	

   		/// Locks the process item.
   	

   		/// </summary>
   	

   		/// <typeparam name="TProcessItem">The type of the process item.</typeparam>
   	

   		/// <param name="processItem">The process item.</param>
   	

   		/// <returns></returns>
   	

   		protected override TProcessItem LockProcessItem<TProcessItem>(TProcessItem processItem)
   	

   Notice it doesn’t fill in the value for “returns,” but if you think about it, there’s really no way for it to know that.  Besides, this is the sort of typing that we should do, because it eventually provides a synopsis of what the method does.
4. Document your code and build your project.
5. Download and install Sandcastle.  Fire it up.  The default empty environment will set you up with a new project.  After saving/naming the project, in Sandcastle’s Project Explorer, right-click  “Documentation Sources” and browse to the build .exe or .dll for your project.  Alternatively, you can use the .Net solution or project file.
   
   
   
   
6. In the Project Properties, find “HelpFileFormat.”  This is how you can configure what sort of help files you want Sandcastle to build.  There are currently three options:
   
   HtmlHelp1x – Standard CHM help file that we’ve all come to know and love, built with HHC.exe, which you should already have installed.
   HtmlHelp2x – HxS help file.  Note that you need to have HXCOMP.exe, which is part of the Visual Studio SDK.
   Website – A rather robust HTML website that looks a bit like an older version of MSDN.  I haven’t experimented with this, but the Sandcastle site has a lot of tips on how to use third-party plug-ins for Ajax and other cool stuff.
   
   
7. Configure all of the other Project Properties in Sandcastle as you see fit.  You’re going to miss some stuff.  Don’t worry, Sandcastle makes it easy to see what you’ve missed.  Leave the log-related properties as their defaults.
8. Under the “Documentation” menu, select “Build Project.”  After a short time, your build will complete.  Navigate to your “OutputPath” folder and look at your awesome new help documentation!  Then, package it up with your project so that everyone can use it, send it to your boss, and go get some ice cream.

While browsing through your documentation and feeling really good about yourself, you may notice some points where Sandcastle will have marked in bold-red font, [Missing <something> documentation for “a particular thing”.]  You can easily repair this by going back to your project and adding the missing XML documentation, or, if it’s a namespace, you can add namespace documentation to the Sandcastle project by using the Namespace Summaries editor found in the Project Properties for “NamespaceSummaries.”  Also, if you would rather not dig through every single page generated by Sandcastle, you can easily find missing documentation by looking at the build log, which can be accessed through “Window—>Build Log Content.”  Sandcastle highlights any warnings for missing documentation in the build log, making it very easy to scroll through and see what you might have missed.

So, with a little extra work (as opposed to a ton of extra work), you can feel a bit better about your documentation habits.  I’ve found that using these simple steps has made me a better programmer as well as a better teammate.  Looking at the output from Sandcastle and adding meaningful information to my code with GhostDoc makes me pay more attention to its structure and design.  That, in itself, makes it worth the effort.