Introducing FubuDocs for “Living Documentation”

TL;DR:  The FubuMVC community is finally getting its technical documentation act together with a new tool called FubuDocs.

The Wrong Way

About 5 years ago I released StructureMap 2.5 with the idea that it would permanently lock the public registration API’s into a new, shiny fluent interface that everyone would love using from now on.  As part of that release, I wrote comprehensive documentation with lots of embedded code samples painstakingly copied into the static html files and published a pure HTML website. Then I started using StructureMap 2.5 in daily work, found out that I hated using the new fluent interface, and immediately changed the public API’s in subsequent releases to smooth out the usability problems.  Unsurprisingly, I never got around to updating the now defunct documentation code samples.  

Moreover, the documentation that I did write wasn’t always helpful to users because the organization of content on the site did not make sense to them and they weren’t always able to find the right content.

Fast forward several years and the FubuMVC community has built a tremendous number of potentially useful libraries, features, and frameworks that nobody knows about mostly because I’m nearly allergic to writing documentation.  To give all our hard work an actual chance to be successful, Josh Arnold and I envisioned and built a new tool for creating and publishing living documentation we fittingly called FubuDocs (the FubuDocs documentation at this link is created and published with FubuDocs itself).

FubuDocs Highlights

  • The documentation lives side by side with the real code
  • We “slurp” sample code directly out of the real code and automated tests so the sample code cannot get out of synch with the current API to avoid the headaches I had earlier with StructureMap documentation.
  • Heavily inspired by readthedocs.org, FubuDocs determines the navigation structure and navigation page elements for you based on the files in your documentation project
  • You can run a FubuDocs project website interactively using the fubudocs tool distributed as a gem.
  • The fubudocs interactive mode exposes a topic manager tool you can use to extend, reorder, and modify the documentation outline.
  • You can use a combination of Markdown syntax and custom html elements to author content
  • Exports the final content to static HTML (we are just publishing to GitHub Pages).
  • It’s “skinnable” — in theory, works on my box, nobody else has tried that yet

 

In a later post, I’ll talk about how we have automated the publishing and versioning of technical documentation within our continuous integration infrastructure.

Advertisements

4 thoughts on “Introducing FubuDocs for “Living Documentation”

  1. Pingback: StructureMap 3.0 is Live | The Shade Tree Developer

  2. Pingback: StructureMap 3 Documentation | The Shade Tree Developer

  3. Pingback: Retooling Build and Test Automation Tools | The Shade Tree Developer

  4. Pingback: How I’m Documenting OSS Projects | The Shade Tree Developer

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s