Over a million developers have joined DZone.

Journey of 1,000 Miles Towards Documentation Nirvana

DZone's Guide to

Journey of 1,000 Miles Towards Documentation Nirvana

· Integration Zone
Free Resource

The Integration Zone is brought to you in partnership with Cloud Elements. What's below the surface of an API integration? Download The Definitive Guide to API Integrations to start building an API strategy.

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!

Your API is not enough. Learn why (and how) leading SaaS providers are turning their products into platforms with API integration in the ebook, Build Platforms, Not Products from Cloud Elements.


Published at DZone with permission of Janet Revell, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}