Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now


Open Channel: Why We Need to Re-Invent Documentation

Documentation can be the Achilles heel of any software—or its saving grace. But is there a better way to teach users?

Craig Anderton
Craig Anderton

Microsoft once created a focus group to find out which new features Word users would like in future versions. The participants filled out their wish lists, except…the requested features were already in the program. I don’t know what Microsoft’s takeaway was, but mine was that Word needed to somehow make users aware of the features it already had, which is not easy with such a feature-rich program.

In music software forums, users also make feature requests without realizing that existing functions do what they want. When some people can’t figure out how to accomplish a particular function, the response from other forumites might simply be a snarky “RTFM,” but you can’t search for something in a manual if you don’t know its name, or whether it even exists.

No wonder those starting out in recording often find that learning a DAW is a user-hostile experience. Even those who persevere may have a nagging feeling that they’re missing the knowledge needed to accomplish particular goals as efficiently as possible.

That’s not surprising: Many DAWs have evolved over the course of years, or even decades. Maybe you can read 1,000+ pages of documentation and retain everything, but I can’t. How can we find out about that little gem of a checkbox you discover only by scrolling down a list of options accessed by clicking on a generic-sounding tab of a menu’s sub-menu?


Restructuring manuals to implement a different teaching model may be the answer. Currently, most manuals are collections of operational definitions for the included functions. That’s necessary, of course. But imagine if documentation added a results-oriented overlay to complement the function-oriented foundation.

For example, suppose you want to reduce vocal p-pops. The documentation probably won’t have a “how to reduce p-pops” section. However, there will be individual sections on how to create fade-ins, how to isolate part of a clip for processing, and what a high-pass filter does. It’s up to you to connect the dots between knowing what these functions do and how they can provide the result you want.

Open Channel: Can Artificial Stupidity Save Us From AI?

But that’s backward! What most users need to know is: If I want this specific desired result, what functions do I need to implement it?

Fortunately, most manuals are PDFs. With Adobe Acrobat, it’s easy to use hyperlinks to explore different parts of a document, then retrace your steps to return back where you started. So, the results-oriented overlay would be lessons that point you to appropriate parts of the manual and provide guided tours through the vast galaxy of facts known as “the documentation.” Each lesson’s premise would be how to reach a particular goal. Then it would give an overview of how to do that, with hyperlinks to sections that describe the needed functions.

For example, a lesson on vocals might be about obtaining more consistent levels so that a vocal stands out in a mix. The lesson could start with explaining how DSP functions can obtain more consistent levels. Then, hyperlinks within that section would transport you to sections about using gain envelopes, clip gain and normalization.

The next step in the lesson might be about cleaning up vocals. The overview would describe ways to reduce a p-pop, and then hyperlinks would take you to the sections alluded to previously—how to do fade-ins, how to isolate specific sections of a clip for processing, and how high-pass filters work.

Additional steps could cover processing using plug-ins, and describe the effects of compression, limiting, and EQ. Again, hyperlinks would take you to the sections that define the functions you’d use. As you went through the lessons, you’d build up your own knowledge base of how to obtain specific outcomes. (If this sounds familiar, it’s based on the “Guided Tours” approach I used for the E-Mu Emulator II manual in 1985. Unfortunately, PDFs didn’t exist back then.)


Now let’s go blue sky and theorize about how to learn about optimizing your workflow. For example, in that vocal lesson, you might not know that a linear-phase EQ could be a better choice to reduce the p-pop because there won’t be phase shifts above the cutoff frequency. Or, you might not know about some keyboard shortcuts that could reduce mouse clicks. Traditional documentation can’t really handle these scenarios.

In these situations, artificial intelligence is a potential solution. Machine learning could analyze your workflow, and over time, AI would make suggestions based on what you do and how you work.

Again, using our vocal example, if you’re working on a track called “vocal,” and the AI sees you insert a standard high-pass filter, it might suggest using a linear-phase one. Then it would ask if you want it added to your plug-in “favorites” folder because you seem to work a lot with vocals.

Our recording and production tools have unprecedented capabilities, yet we still have the documentation model used for simpler programs of decades ago. If we want to keep tomorrow’s potential superstar engineers from giving up in frustration, maybe it’s time to change how they get up to speed on learning about recording with computers. And overall, it would help everyone get more out of their software.