Building Sandcastles … great Codeplex artefact for the documentation focused!

  • Article

Clipart Illustration of a Group Of Four Colorful Diverse People Lying In A Circle With Their Heads ConnectedAs part of the VSTS Rangers projects (see list of current projects here), we are running a number of team technology briefing and training sessions. Today’s session “VSTS Rangers Project - TFS2TFS Project Copy: Sandcastle briefing” was intended to introduce the team members to the Sandcastle product.

Overview

Codeplex sandcastlelogo_jpgproject description and I quote in italics and include the Sandcastle image from the CodePlex site:

“Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the following key features:

  • Works with or without authored comments
  • Supports Generics and .NET”

Find the bits here: https://sandcastle.codeplex.com/ and if you are a fortunate MSDN Magazine subscriber, you will find an excellent article on Sandcastle in the May 2009 edition.

What we learned and saw in today’s briefing

Highlights

Jeff listed the following in his presentation:

  • Produces quality, comprehensive, familiar MSDN-like documentation
  • Works with or without authored comments
  • Supports all .NET languages
  • Supports Generics and .NET Framework 2.0, 3.0, & 3.5
  • Supports .NET Compact Framework projects
  • Very fast performance
  • Supports localization

Demo

The demo was the exciting part, because the documentation came to life from inline comments as shown:
image

Conclusion

The only challenge I see at this stage is the integration and maintenance of visualisation models, i.e. diagrams, and the possibility of the documentation being done as an afterthought, resulting in code churn, destabilisation and maintenance. As Jeff said, documentation should be planned from the beginning and resources must be dedicated to creating comprehensive comments in the source … I guess the old saying applies: “Garbage In Garbage Out”, or GiGo in short :)

However, other than the maintenance and planning concerns, which are part of the application lifecycle management (ALM), the tool and especially the visual GUI are exciting. Have a look and evaluate the tool!

It was definitely worth getting up early … thanks Jeff Bramwell (MVP), for an interesting and valuable session.