The MuleSoft Content Experience team has been busy. In the last few months, we’ve created new docs to help launch API Governance, Flex Gateway, CloudHub 2.0, and MuleSoft RPA, just to name a few. But documenting new products and features isn’t all we do.
An essential part of our mission statement is to build strong, lasting relationships with our users, who are both consumers and collaborators of our content. Building those relationships goes beyond crafting excellent product documentation. We’re constantly working to improve both the content and the user experience on the MuleSoft documentation site. With that in mind, check out this roundup of some enhancements we’ve recently rolled out.
Focusing on accessibility
Earlier this year, MuleSoft kicked off a company-wide initiative to improve accessibility across our product experiences, including documentation.
As part of this initiative, writers took the Writing for Web Accessibility trailhead. In this training, we learned how and why to use accessible structural components (like consistent headings, tables, and lists); what makes language accessible (keep it simple and don’t use jargon); and the importance of alternative and descriptive text for images. Now, accessibility considerations are part of our review and editorial process.
Behind the scenes, our docs engineering team has also been working to make the MuleSoft documentation site more accessible, for example:
- If you use the keyboard to navigate the site, you’ll notice a new border with better color contrast when navigating elements on the page. The border also now lands on the toggles that expand or close a top-level node in the site navigation.
- Hyperlinks are now highlighted for better visibility when you hover over them.
- Section anchors now use an actual image link and alt text, and external link icons now contain alt text.
- The site now uses aria-labels for screen readers to highlight when a user expands or closes a top-level node in the navigation.
- The borders and placeholder text for search boxes are now darker for contrast. Additionally, the search modal is responsive to screen type and size.
You can expect more accessibility improvements in the future.
Ensuring inclusivity in the docs
Alongside the accessibility project, MuleSoft is also running an initiative to remove non-inclusive language and potentially offensive terms from our products. In collaboration with the Salesforce Content Experience team, we’ve created guidelines for this project and are working to replace a number of non-inclusive words and phrases from MuleSoft products and docs.
Bringing uniformity to release notes
Release notes are a critical part of product documentation, as they contain information about new features, bug fixes, and known issues in a given release. To bring more uniformity to MuleSoft release notes, we created a new template and a handful of language guidelines for writers and product managers to follow, for example:
- Write new feature descriptions in terms of how the new functionality benefits users.
- Write fixed issue descriptions in terms of how the user experienced the errors or bugs.
Additionally, we analyzed the types of issues and defects we document in the release notes. As a result, we created specific guidelines for documenting the different issues and defects, including issues that returned error messages, demonstrated incorrect behavior, resulted in the creation of new components, or were the result of updated or deprecated libraries and security fixes.
These guidelines enable us to craft release notes that demonstrate consistency across products and release notes language, while providing product information that’s most useful to the users.
Getting interactive with DataWeave
The DataWeave language helps users extract and transform data when building business-critical workflows. To help our users better experiment with their transformations, DataWeave examples in the documentation now load automatically into the DataWeave playground with the click of a button.
Just open one of the examples, and click the flask icon to load the script and any input into the playground:
The playground automatically processes the loaded script along with any input payload from the example. From the playground, you can modify the script and input as you like to meet your needs.
Other useful, user-focused changes
We’re also pleased to announce additional user-focused changes.
Promoting the Anypoint CLI documentation
For some time, we had a work item in our architectural backlog to move the Anypoint CLI out of the Runtime Manager documentation, as it has evolved to encompass more than just Runtime Manager.
The CLI is now a mature and comprehensive tool that enables users to programmatically manage not only application deployments but also API Governance rulesets, Exchange assets, and DataGraph API source, among other things. With that in mind, we moved the CLI documentation to its own versioned top-level node in the docs site navigation.
Adding Versioned Docs and EOL Banners
We know our users commonly land on our site through Google searches or through searches on other MuleSoft properties, but those search results aren’t always accurate. More than a few times, users have opened support tickets because they landed on a particular doc but didn’t realize they were viewing an outdated or incorrect version of that information.
While our site does include some affordances (like version tags in the navigation) to show what version of the docs you’re looking at, we realized that wasn’t enough. To address this, we added a banner on some versioned docs to let users know that they might be looking at an incorrect version.
The versioned docs banner ensures users get the most up-to-date documentation: 
We also have a banner for products that have reached end of life (EOL): 
The EOL banner warns users when a product is no longer supported. And we’re definitely working on that site search!
Archiving the Old Stuff
Our product portfolio has certainly changed over the last few years. Needless to say, we have plenty of legacy product documentation on our site we don’t really update or need anymore. To this end, we recently launched a documentation archive site, and we’re currently working on moving legacy docs to the archive from our production site. Archived documentation includes Data Gateway, Healthcare Toolkit, and Partner Manager 1.0.
Don’t forget – you can contribute to the docs
These are just a few of the many improvements we’ve recently made. Our work definitely continues. We’re tweaking the landing page, experimenting with video tutorials, and working on structural changes for a more task-based user focus in our site navigation.
In the meantime, don’t forget that you can contribute to our docs, too.
Much of our documentation is open to public contribution. You’ll know a docs repo is open to the public if you see a *View on GitHub* button; if you’re interested in contributing, click it! In the repo, you’ll find instructions for completing a contributor’s agreement, our code of conduct, and you’ll have the ability to submit a pull request that we will promptly review.
Finally, be sure to follow us at @MuleSoftDocs on Twitter to keep up with all the latest changes and documentation releases.
