Journey of a Thousand Miles Towards Documentation Nirvana


In the journey of a thousand miles towards world-class documentation, we have taken the first few steps!

Long a candidate for improvement, Mule Documentation has recently undergone several foundation-layer improvements that will help us move more quickly as we produce new content and clean up the old. Listed below are a few changes aimed at dramatically improving the user experience for our readers.

  • Merged Content – Where once Mule documentation existed as “silos” according to product, we have now merged all our content in one place on  No more grappling with disconnected pages and broken links– you can now access everything from one left-nav directory tree.
  • Version-specific Content – Where once our documentation existed in one of two piles (“old” or “new”), we have started separating the content according to the version of Mule software to which it corresponds. To access these versions, you can use the new Versions drop-down on the upper-right corner of each document (see below). For now, the “3.2.X”  version contains materials pertaining to Mule 1.x through 3.2.x, but we plan to disambiguate the version of these archived docs in the future.

  • Documentation for Multiple Interfaces – We have introduced new functionality in our documentation that allows us to embed “tabs” in our pages (see image below; see example). These tabs enable readers to easily switch from Studio-specific instructions to XML-centric instructions with one click.  (Now all we have to do is update all our Studio-centric content with XML!)

  • Flows and Gists – We have nearly completed a project to update our content to reference “Mule flows”, rather than “Mule services”, where appropriate. Importantly, wherever we adjusted a code snippet, we did so using a Github gist. Eventually, we plan to use gists to map all (or at least most) of our code snippets to git repos so that we have a method of maintaining them that is both accurate and timely.
  • Star Rating – We have begun to actively collect feedback regarding our documentation.  Have you noticed the star rating mechanism at top and bottom of each of our pages? We want to know what you think! Give us a 5-star rating if you liked what you saw; slap us with a 1-star rating if we fell short of your expectations. We review the ratings each business day and, if you include your email address, we’ll let you know how we’re addressing your comment.

Our journey to improve documentation has just begun, but we’re excited by our progress and the traction we’re gaining as we pick up the pace. Stay tuned – it’s bound to be an interesting expedition!

We'd love to hear your opinion on this post

One Response to “Journey of a Thousand Miles Towards Documentation Nirvana”

  1. Very nice improvement to the documentation on the site. For those of us that aren’t always into the graphical flow views and like to see the “guts”, love the toggle to see the XML for examples. Well done!