Enterprise Integration Zone is brought to you in partnership with:

Working as a tech writer and PM in the software industry for 5+ years, Janet joined MuleSoft in 2011 and learns something new about systems integration everyday. Janet is a DZone MVB and is not an employee of DZone and has posted 2 posts at DZone. You can read more from them at their website. View Full User Profile

Journey of 1,000 Miles Towards Documentation Nirvana

03.19.2013
| 2385 views |
  • submit to reddit
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 www.mulesoft.org/documentation/display/current/home.  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!

Published at DZone with permission of Janet Revell, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)