Introducing FubuMVC.CodeSnippets for living documentation

TL;DR:  FubuMVC and its related projects are finally getting some documentation, and the FubuMVC.CodeSnippets library is a big part of the “how” we’re trying to make the docs easier to write and maintain

Once upon a time there was a man who worked on an open source tool named “StructureMap.”  This man spent an inordinate about of time on his 2.5 release, crafting a comprehensive set of documentation in static html as part of that release.  Upon making the long awaited release, some unpleasant things happened:

1. Many people didn’t like or just couldn’t derive any value out of the documentation website because of the way it was organized
2. This man quickly realized from his own usage that many of the new API’s were awkward to use and he immediately added alternative API’s to make StructureMap 2.5+ usable
3. It wasn’t easy to edit the big pile of html and copy/pasted code samples, making the effort even more painful — so the docs and the actual API wildly diverged and didn’t help the poor man handle user questions

Since I’d strongly prefer not to be that guy ever again, we’re putting some effort toward using “living documentation” techniques for FubuMVC, Storyteller, and StructureMap 3 to make it as easy as possible to keep the documentation in synch with the various frameworks as they evolve.  As part of that goal, we’re using the FubuMVC.CodeSnippets (check out the link, there’s real documentation developed with FubuDocs) library to “slurp” sample code snippets right out of the live code during the automated builds.  This way we can simply reuse unit test code and bits of example code running in the CI.  If the real code changes, the sample code and the unit tests would have to change too or the CI build breaks.

In a nutshell, the idea behind FubuMVC.CodeSnippets is to just add some comments into your code marking the boundaries of a named “snippet” like so:

// SAMPLE: snippet-name

// C# code in the middle.

// ENDSAMPLE

In a FubuMVC view, you can just say “I want to display snippet named ‘snippet-name'” and the view helper for code snippets will add the raw code in a <pre> tag and use prettyprint to color code the code.