This guest blog post was written by Una Cogavin, a certified MadCap Advanced Developer and MadCap Flare consultant. Una is a director of The Docs Team, which specializes in converting all types of legacy content to MadCap Flare. In addition, The Docs Team supports software startups with an out-of-the-box, virtual, on-demand technical publications and content strategy team.
Ever find yourself going down a rabbit-hole looking for the content you need? Topic writing, which should provide everything you need about a single topic, can produce an indecipherable web of links that leaves you lost. Most people go to content when they need to find a solution to a problem that they are currently experiencing.
As a technical writer, I want to believe that I understand exactly what kind of material the reader needs. However, the reality is that we cannot serve all readers with just one method for retrieving content. While search is the foremost method for discovering content, modular content, based on a well thought out content model, adds a great second method. Modular content provides the framework for content relationships and focused navigation paths, without giving up search.
What is Modular Writing?
So what is modular writing? At the basic level it seems pretty similar to topic writing. However, modular content adds relationships and organization that assembles individual pieces of content into cohesive narratives that can be used to perform more complex activities or user journeys. And modular content doesn't stop at the literal content the user reads. It also encompasses each aspect of defining and building the content, whether it be defining style sheets, creating templates, or using conditions to include or exclude content. Each can be separated and considered a module of sorts because they are interchangeable. If you think about agile and writing sprints, they also have a modular aspect, so you can even manage technical writing projects using a modular process.
How Modular Content Benefits Readers
Modular content supports discoverability and exposes relationships that glue individual topics and content together and provides navigable sign posts to readers. Assembling and reusing blocks of content into a meaningful organization. It is mostly about organizing content based on a category. Categories can be based on product functionality, training goals, user roles, or user journeys to name a few. While topic-based writing aims to have all you need to know in one article or page, modular-based content aims to organize and relate content based on your organization's chosen categories.
Modular content enhances the discoverability of content. A reader might think they know what to search for, however what if they could discover alternate product functionality that better addresses their needs? A good example of discoverability benefits can be seen in an API reference example. The reader could be looking for an API that exports a file. They use the search term "export" and see the search result "Export by filename" for an API reference page.
The organization of the navigation bar shows an article called "Download by folder name." Because the content was modular-based, the two articles could be shown together. The reader sees the association and knows they can save time and effort by downloading or exporting a whole folder of files instead of individually, by each filename. Using a modular content structure allows for a very helpful navigation layer that the reader can use to discover related information.
How Modular Content Benefits Writers
You've seen how modular content benefits readers, and, as technical writers, we focus on the best experience for our readers, right? If that's not enough motivation to start following modular content practices, then here are some benefits to writers.
From the writer's perspective, modular writing can help you stay organized and be flexible in an environment that is busy with a complex or ambiguous environment. Have you ever been so overwhelmed that you just can't stay organized? Modular writing can allow you to write basic level content for every feature, and help you negotiate and stage deliverables for more advanced content. It also helps you to switch quickly to writing a different feature when product goals change. For example, feature A is no longer a priority, instead you need to get up to speed on feature B.
Modular content also lends itself to the ease of distributing writing tasks to two or more writers. Each writer can be sure their writing changes will not overlap content that another writer is working on. If you need to quickly move additional resources onto a project to get content out faster, without modular content, you'd need to coordinate when each writer could have access to shared files.
Tools to Produce Modular-Based Content
To produce modular-based content, you'll need writing tools that support the modular concept. Using tools that allow you to write only in a serial fashion seriously limits your abilities to produce modular content. While some talented, detail-oriented writers could probably spin up a tracking spreadsheet, there really is no need to anymore. There are professional tools that manage content and allow you to implement modular writing content strategies.
Let's look at several areas where a modular strategy and the right tool can enhance your ability to produce content that is modular. For example, using a tool like MadCap Flare, you can create modular topics, snippets, and variables that are reusable, use TOCs to bind topics into meaningful content modules, use templates to consistently define each type of content, and use interchangeable CSS and skins to deliver modular content to the Web, mobile, or print audience.
Topics
Starting with topic-based writing, you need a tool to support writing individual pieces of content that can be assembled into various content modules. Reusing the topic in the same content module, if required, or in a completely different module. Within individual topics you can include snippets whose content can be managed separate from the content in the topic. For example, suppose you need to include some legal information that needs to be reviewed by legal. Including a separate snippet makes it easier to keep it up-to-date and reviewed by legal.
In addition to topics and snippets, you can use variables and conditional content. Variables allow you to separate general content from, for example, a version number or a feature name, any content that has a tendency to change regularly. Modularizing these types of content makes delivering content faster and more flexible. It also reduces errors from copy and pasting content or from forgetting to update several different sections that have the same content. MadCap Flare supports topic-based writing, snippets, variables, and the conditionalizing of content.
Templates
Creating templates that define how you structure specific types of content are key to modular content writing. Templates allow individual writers to produce brand compliant content. Rolling out a consistent look and feel aids the discoverability of content. Templates also remove the need for the writer to figure out how to structure content each time a new topic is written. MadCap Flare supports creating template project files that you can keep updated in a central location, then other projects pull updates from this central template project.
TOC
Bringing the content together into an intelligent content structure takes planning and is time consuming. You need a tool that lets you quickly design and test proto-types. MadCap Flare is excellent for fast prototyping. You could conditionalize modules for a different audience, and then reuse the same outline to produce different types of output. For example, in MadCap Flare you can build one TOC for both online and print by simply conditionalizing the usual print-only content and excluding it from the online output.
Web, mobile, and print outputs
Audiences consume content on the Web, mobile, and even in print (or PDF). You can separate your actual content from how you deliver it, whether it be Web, mobile, or print. Using modularized skins and CSS enable you to produce all the types of output from the same content. Using CSS you can choose completely different fonts and paragraph styles to suit the medium the content is being delivered in.
MadCap Flare's CSS management is easy to use and provides both a text-based and UI-based method of defining styles. And skins allow you to decide whether you want a modern HTML5 look and feel on the Web or if you need to produce content that is specifically designed for the smaller mobile screen. Because each skin and CSS is a separate module, you can interchange and publish. MadCap Flare provides default skins that allow you to get started quickly and focus on customization later.
Summary
There are many benefits to modular content writing both to the writer and the reader. Modular content lowers costs, reduces time spent, and creates an organized workspace for writers. And managing modular content gives you a framework for negotiating deliverables and timelines.
Modular content also helps to produce a frustration free experience for readers. Most people go to content when they need to find a solution to a problem that they are currently experiencing. Providing easily discoverable content that has built in relationships to broader content, and which is accurate, will give your reader the best experience. Readers will trust that you respect and value their time, and they will come to your technical documentation again for the solution to their next problem.
