Documentation, the Mindscape way

A question has been asked in our forums about how we create, maintain and publish the documentation for our products and rather than just reply in the forum I thought it maybe of interest to other software developers out there.

First off, if you haven’t read our help files for fear that they’re just simple API documentation you’ll be pleasantly surprised to see that we provide both API docs and a more human-readable discussion of various key features. LightSpeed’s documentation even includes a getting-started walk through to help guide new users to creating their domain models faster.

API documentation

Our API documentation is extracted from our XML doc comments in the source code. We turn on XML documentation generation which creates and XML file containing all the documentation for every class, method and property. This means if you’re an enterprise customer who receives the source code to our products that you’ll see these comments inline. We also turn on the static analysis and ensure that Visual Studio will provide a warning if there is a missing doc comment as it’s certainly very easy to forget to create one. To keep us honest (and to laugh at those who forget) we also turn on the compiler option to show warnings as errors so that our continuous integration environment will show a broken build if a doc comment is missing.

That brings us to having the raw source for our standard MSDN-styled API documentation.

Hand written documentation

We have those nice hand written documentation guides around key features. For those of you who are unaware of how windows help files are constructed, they’re effectively HTML pages grouped together with some table of contents meaning that these pages in our documentation are hand written html pages.

Because writing heaps of html by hand is somewhat tedious we use a Ruby utility called WebGen which can generate static html from pre-defined templates. We write our html documents using a textile like style markup (I say “like” because it includes some WebGen specific mark-up as well).

Code Samples

Code samples are always nice in documentation but the pain of maintaining documentation is that as your code changes these samples start to rot and don’t reflect how you would actually use the API. To overcome this we have a plug-in for WebGen which will extract code from our actual product unit tests. To paint a picture, here’s what we would have in our WebGen template:

{sccode: {region: Representing a one-to-many association, file: Domain/Member.cs}}

What this does is open up the file, Member.cs in the Domain directory and find the code wrapped inside the region tag with the region name of “Representing a one-to-many association”. It then injects it at that point in the template and nicely wraps it in syntax-highlighted goodness.

The nice thing about this is that we know that the code samples in our documentation at the very least compiles but also, because it comes from our tests, we know that it performs as expected. It also means that if we change our API and a test breaks that we’ll know and can update the test and then the documentation change will be reflected in the next nightly build.

Putting it all together

Once we’ve generated our xml API documentation and generated our static html pages for our hand written documentation with WebGen, it’s time to compile everything together into a single CHM file. For this we use the excellent Sandcastle Help File Builder (SHFB) and Sandcastle. Sandcastle is a collection of utilities and templates, created by Microsoft, for generating CHM files (as well as other types of output if you so desire). SHFB is a very nice visual application for automating Sandcastle and I highly recommend to anyone undertaking documentation generation.

Once we’ve configured things such as the table of contents, included our custom html pages into the structure, give standard documentation names and links to our help file inside SHFB we can save the SHFB project file for later use. This is handy because the SHFB comes with a command line version as well which integrates directly into our continuous integration environment so that every nightly build that we make available comes with a freshly minted version of our documentation.

Could we do more?

Beyond what I’ve covered here for our CHM help file that ships with LightSpeed, the WPF Property Grid and WPF Elements we also provide an HTML version online however I always feel that companies can do better with their documentation. We have received comments in the past about improvements in certain areas and have always acted on that feedback. Is there something more we could do in terms of documentation that would make you happy? If so – drop a comment here or, even if you don’t have feedback but a question about documentation, feel free to ask away.

kick it on DotNetKicks.com

2 Responses to “Documentation, the Mindscape way”

Archives

Join our mailer

You should join our newsletter! Sent monthly:

Back to Top