What's Up, Docs?
November 30, 2017 by Michael Evangelista
Exploring Mura 7 Documentation
Every software product has a story. From inception to outline, prototype to production, the steps involved with bringing a multi-faceted codebase to life are generally far more complex than many of us may ever know, often by design.
However, some knowledge of the history and thought process behind a product can go a long way towards understanding the intention of its makers, and promoting Flow when putting that product to use. When it comes to software, the documentation tells that story.
Applying insight to expertise
Mura CMS is currently at version 7.0, with a 7.1 release on the horizon. While the development team has always been mindful of offering assistance and plentiful resources to Mura's end users, including the well-traveled docs.getmura.com, we have also accumulated many more collective years of experience with providing support, training and code examples to the community.
Since the creation of the "v6" documentation site, a lot of things have changed. Mura 7 introduced a major revision to the user interface, along with new functionality for front-end editing, display object management, and streamlining the overall content workflow. In addition, many developer-centric enhancements were added to the code. Some of these are invisible until exposed through examples and documentation.
As we began the process of adding new screenshots, features and examples to the existing docs, it became abundantly clear that a simple rewrite wasn't going to cut it. Steve Withington, blueriver's lead trainer and education director who spearheaded the documentation overhaul, explained, "Due to the all-new UI, functionality enhancements and codebase improvements, all of our documentation needed to be revisited and updated. When I began the review process, I quickly realized this was going to be much more than simply updating some UI screenshots, and tweaking the existing language." The docs would ultimately require a complete rewrite, and more importantly, a thorough restructuring.
Calibrating the approach
In the past, Mura's documentation was tied very closely to our training curriculum, in which the primary goal was to build a brand new site from scratch, learning about Mura's inner workings along the way. While this approach worked well in a classroom environment, it wasn't quite as useful when attempting to figure out how specific areas of Mura worked, using only the online documentation.
What's more, the traditional dichotomy of "Front End" versus "Back End' developer education has become blurred in recent years, with many more teams and multi-talented devs blurring the lines between those roles. In order to eliminate distractions, boost developer confidence, and minimize time spent looking for solutions, the all-new Mura 7 documentation breaks things down along different lines.
The Content Manager Guide is aimed at anyone wanting to manage content in Mura, and explains how to create, edit, and delete content from both the front-end and back-end areas of Mura, with a bonus section for "Groups, Users, and Access Control" which also covers essential pieces such as permissions and publishing workflows.
The Theme Developer Guide focuses on working with themes and layout templates and customizing Mura's "default" output, with an emphasis on helping designers or developers familiar with HTML and CSS to convert their designs (or someone else's designs) into a Mura CMS theme. This means a "Theme Developer" should be able to create the basic layout templates including Mura's basic content attributes such as body, title, and navigation, then hand the theme over to a "Mura Developer" to flesh out some of the more complicated static pieces with live, dynamic content.
The Mura Developer Guide fills the gaps not covered in the Theme Developer Guide, then goes much deeper into integrating custom business logic and applications into Mura.
While some of the base structure from prior versions is still present in the new documentation, the contents have been reorganized to better accommodate the way most developers digest and retain information. As Steve points out, "This was probably one of the most challenging aspects of writing the developer guides. We had a ton of 'chicken and egg' information to cover!"
There's even a specific section solely for the development of plugins and other tie-ins to Mura's interface, entitled "Mura UI Markup Conventions", which provides in-depth examples and explanations for extending the Mura UI with forms, tables, tabs, configurators and other common elements.
We encourage all Mura users to explore the documentation at length and utilize the search and navigation options to find specific mention of certain features or functionality as needed. An unprecedented level of detail has been added to the version 7 docs, practically guaranteeing that even those most familiar with Mura will pick up some new inspiration and knowledge, simply by perusing the various sections.
Continuing the Conversation
While obviously crucial to the overall success and growth of Mura's user base, the docs are only part of the greater story. As we look towards the release of Mura 7.1, and beyond, our aim is to continue providing an ever-increasing array of helpful content in the form of updated documentation, webinars, and informative articles at every opportunity.
As always, your feedback is welcomed and appreciated. Tell us what you find useful, suggest an addition the documentation, or drop Steve a line to let him know you've learned something new. Feel free to share documentation links with your team members, clients, employees or end users at will - this freely-available resource exists with the sole intention of reducing friction, minimizing guesswork, and increasing Flow in every aspect of Mura development.