This guest blog post was written by Homer Christensen, an award-winning technical writer and UX designer, an Information Architect, MadSkills consultant, and an award-winning tech writer and UX designer. His client list includes Nestlé, Microsoft, Ellie Mae, Conga, and the State of California. When not writing or coding, he’ll likely be bikepacking, winemaking, or enjoying his permaculture garden.

There is a truism that All Documentation is Training, and by correlation: All Reading is Learning. Not too long ago this seemed a bit of a stretch. Now, it’s edging towards reality.

Over the last few decades, software documentation has changed dramatically. Readers turned into users and it’s common now to describe our audience as learners. User manuals morphed into knowledge bases to learning centers.

But it isn’t just nomenclature. There has been a fundamental shift in the way that documentation is valued within the corporate structure. Documentation had historically been viewed as a cost of doing business. It was typically understaffed and a team you were promoted into from customer service.

Training, on the other hand, was often a profit center, staffed by skilled professionals. (Their emphasis, not mine.) The two were historically different and separate, at a loss to each, because they’re a natural pair.

Documentation and training teams are typically integrated (or at least aligned) now, thanks in large part to software applications like MadCap Flare that enable information content—concepts, procedures, and reference materials—to be published in multiple formats and platforms. When done right, this blended approach offers cost savings, consistent information, and a synchronicity that makes each more engaging.

I was drawn to instructional design—and the role that an instructional designer can play—early in my career because I enjoyed writing tutorials and classroom guides. It’s been integral to all of the work I’ve done since, whether software user manuals, SQL Server classroom training materials for Microsoft, context-sensitive help for the State of California (which we later quickly repurposed for training materials), or at my current assignment at Nestlé to create internal, online learning centers for diverse audiences and topics including manufacturing, travel, and human resources.

What makes instruction and instructional design so satisfying as a writer and developer is that your end product is more learner-focused. You’re an advocate for the learner and, at the end of the day, they leave with skills that let them do their job better, hopefully with fewer errors, and with greater advancement potential and job satisfaction.

The same process used to create a solid instructional design model can be applied directly to your documentation flow, regardless of whether you follow a waterfall methodology or Agile.


The most common instructional design methodology is ADDIE, an acronym for the sequential approach of analysis, design, development, implementation, and evaluation.  Here are some of the best practices I recommend for each phase:


If it isn’t you, determine who are the key stakeholders and meet with them. It’ll be imperative to discover what they see as the gap in the current knowledge and what successful completion looks like.

You’ll also want to identify the audience and learn about them, if you don’t already know. How do they like to learn? What level of knowledge are they starting at? What is the best medium to reach them with the training you’ll want to create?

Determine what resources are available to you, whether internal or external. External resources are sometimes a quick way to develop the core knowledge of instructional learning design if your instructional design team is not experienced.

Once you know the extent of the knowledge gap, the training you’ll need to develop to close it, the audience who’ll receive it, and the persons available to put it together, you’ll be able to determine the best way to deliver that training. It might be entirely through a straight-up HTML website, web and print, or some hybrid approach that includes a learning management system (LMS) such as iLearn.

At the end of this phase, you’ll usually have a high-level view of the project and schedule, the needed resources, potential applications you’ll want to use, and clear directions as to what you need to successfully complete it.


Building on the analysis, the design is perhaps the most exciting and crucial phase to the success. Sure, development is where your team will actually create the material, but a solid foundation is key. And designing a learning project that excites you and your team will translate into engaging material. Set up brainstorming sessions to capture fun ideas on keeping the learner’s interest or unique ways to deliver information.

Instructional design includes the look and feel of the training materials, but the focus is squarely on creating a solid instructional strategy. Learning is incremental and your analysis and outline will guide you in ensuring that the learner can advance in a safe and supported manner to the required level of competency and achieve the learning objectives set out. Good analysis will make this easier.

Look for ways to reuse instructional content. This saves not only effort to create material, but saves review time, which is often in short supply as a learning project nears launch. For the State of California project, we saved all tasks and introductions as snippets, set up master pages for web and PDF output, and defined condition tag sets that enabled us to quickly turn around classroom instructional materials. Subject matter experts could review Instructor guides and have high confidence that the materials were consistent with the context-sensitive help and student materials. Updates were synched automatically, except for text that was specific to the classroom.

A hallmark of good instructional design is clearly defined set of learning objectives, or learning goals, of what learners should know before they begin, what they’ll learn in each section, as well as what are the expected learning outcomes. You can incorporate these into introductions with short bulleted lists, which can serve as handy checklists for developers assigned to those topics.

Learning paths are like going for a hike. Ideally, you’ll keep it at a pace that is enjoyable: neither a slog nor a sprint, not too steep or rocky. The path should be clearly signed, with no chasms that learners are expected to jump.

Include different types of activities to engage learner brains in a way that provides multiple natural ways to remember what’s important or understand high-level concepts. Illustrations and infographics are great ways to break up the page and support visual learners.

For novices who may not have the requisite knowledge, provide a path for them to get to a level that elevates their confidence and makes their learning experience successful.

You’ll end this phase with a solid outline of the content you’ll create and the approach you’ll take to make it happen. Because Flare is so extensible and uses standard web technologies, you’ll be able to develop most, if not all, of your design using it. However, some things such as quizzes and surveys are quickly performed using single-purpose apps or websites, and you can offload that work to them. Likewise, if you need to track training, you might link to an online course or a knowledge test developed in an LMS.

Before you go on to development, however, I’d recommend getting a full sign-off by the stakeholders. Do a presentation, if you need to, and create wireframes or a sample of the pages and templates you’ll use in the training. Changes are much simpler in this phase than after development begins.


You can follow your current development methodology as your team creates the instructional content. Having the clear outline as well as the learner expectations/outcomes will help target the writers and developers to address the key learning points.

Keep the learning content focused and brief. If you’re providing a companion web site and student PDF materials, set a standard for what material goes in each and use condition tags to hide content where needed.

Use second person, present-tense, active voice as if you’re conversing with the learner in real time. Use friendly and supportive phrases without getting too wordy or cloying. Depending on the audience, keeping it simple and direct is often best.

Formalize a system of peer review before each chunk goes to the subject matter expert. MadCap Central, if your team is using it, is a convenient and efficient way to review and leave annotations or make corrections and suggestions. For PDF output, print copies to ensure that page breaks are appropriate and any conditioned output is hidden. And absolutely catch any spelling or simple grammar issues before an official review.


Once your content is polished, you’re ready to implement it. A soft launch, where you release the content to a small representative audience to capture their feedback and retention, is a good way to quickly correct any missteps prior to releasing wide-scale.


Breathe a well-deserved sigh of relief after you’ve implemented your training. Then, review any feedback and analytics you’ve gathered to see how you can improve this material as well as lessons going forward with other training. Measure as much as you can, including bottom-line items such as reduced support calls.  And then share those victories with stakeholders.

Evaluation changes the cycle from a circle to more of an ascending spiral, where you start far from ground zero and get the opportunity to refine your materials. This makes the experience more enjoyable not only for the learners but for everyone involved in the process. And after all, aren’t we all learners?