Writing software documentation guides is one of those unique crafts where if it's done correctly, you don't notice it at all; it blends into the woodwork of a successful support community. If the documentation does its job right, our end users find their software answers, and usually don't give it a second thought once they navigate out of the guides. This blog post will give you some secret insight into how the Community team makes this self-service support resource possible. A huge part of that success is well-organized, well-written documentation. The old maxim says it best: "Easy reading is damned hard writing."
Why Overhaul What’s Already There?
To make sure all of our documentation is easily accessible, organized, and helpful to our users, the Community team occasionally performs overhauls of our existing documentation. We've recently started one of these overhauls for the MasteryConnect documentation. We're doing this to ensure the style, voice, clarity, and terminology of the MasteryConnect documentation conforms to the established style of all the other Instructure documentation guides.
Fun fact: Yep, we have a very specific and intentional writing style for our documentation guides! In fact, our internal documentation style guide is 58 pages long.
What Do You Mean by ‘Overhaul’?
So what does a documentation overhaul involve? For the MasteryConnect guides overhaul, we're going through several phases of edits, so that the guides remain accessible even while we're hard at work making them better.
First, we are going through each manual (the first one completed is the Reports manual) to review, retitle, and rewrite each and every lesson. Then, once every lesson has been rewritten to adhere to our style guide and include all the information it needs to include, we look at the manual as a whole and identify if there are any software features that we need documentation for, but don't yet have.
We then create new lessons so that the guides in the manual completely document the various features and functions of the software. Lastly, we reorganize the guides and chapters within the manual so that it flows along with the likely workflow of our software users. After we reorganize the guides and publish them in the Community, we move on to the next manual until all the manuals for the software are updated and improved.
Since we do all of the overhaul work in addition to our regular software release guide updates, there are many contributing factors that make timelines and delivery dates for the overhaul tricky to predict! Another challenge in predicting the timelines for this project is that we don't discover how intensive a makeover each manual needs until we get in there and start the guide revisions. Writing large compilations of documentation is a process that often involves revisions and re-thinking things on the fly. Being flexible allows us to make sure we're staying on course to reach our goals for the quality and helpfulness of the guides.
What Does This Mean for Me?
Be on the lookout for reorganized, polished, and some brand-new MasteryConnect guides throughout 2022! We’ll be publishing them one manual at a time. Check out the Reports manual for a sample of what's coming down the road.
