Best practices for writing modular content

This post will help you plan and create modular content that can work in different scenarios and channels.

The process of creating modular content is unlike writing webpages, where one person writes all the content for a page at once. When developing modular content, pieces of content are written at different times, possibly by different writers. Content teams should develop guidelines and shared practices so that all contributors produce content in a consistent manner.

Principles of modular content: why is it important?

Modular content isn’t a new idea, but interest in it has grown recently. As more content is experienced interactively – rather than read all at once on a single webpage – content designers have sought to make content more modular so that it can adapt to the customer’s context. The growing adoption of headless CMSs, which support the structuring of content into modules, has simplified the implementation of modular content in user interfaces.

Some writers will refer to modular content as content chunks, content layers, or content slices. Each of these terms refers to the structuring of content to allow readers to consume messages and information more easily.

How can organizations build sophisticated content experiences from modular parts?

Modular writing involves three concepts:

1. The content relating to larger experiences is divided into modular pieces
2. Many of these pieces can be reused or substituted
3. Pieces can be connected in flexible ways or in different orders

Writers can combine different pieces into multiple arrangements, much like a toy construction kit such as Lego®.

Like a toy construction kit, modular content makes the experience of interacting with the material more enjoyable. You can compose a range of experiences, not just one.

Modular content can make experiences better too, so it’s easier for readers to use and understand your information and messages. “Bite-sized” messages and information can be customized to match customer needs and optimized so that their wording is ideal.

Modular content can be configured in alternate ways. But connecting pieces of online content is more involved than snapping together a construction toy. Writers need to understand the composition of the pieces:   

• How should you break your messages and information into pieces?
• How should you write these pieces?

Making content concise and compact is hard without first investing in planning. Many distinguished writers agree with Pascal, who famously said: “I have made this longer than usual because I have not had time to make it shorter.”

Modular content requires a plan – and knowledge about how to create useful modules. The pieces created need to fit together into a coherent whole. Until the entire team is familiar with writing modular content, it is a good idea to have a chief editor review all content before its publication to ensure it conforms to the goals.

Break down your communication goals into distinct pieces. Interactive online content can be presented in multiple ways. But to become interactive, it needs structuring.

Writers are already familiar with breaking content into pieces for traditional articles. For example, a customer story or case study could be broken into the following pieces:

• Summary (what this story is about)
• Introduction (why the issue is important)
• Approach (how the customer decided to solve the issue)
• Results (what happened?)
• Conclusion (so what – what is the bigger implication?)

Every piece has a specific role to play. Each customer story might include a piece talking about the approach the customer took. All these pieces would be similar because they have the same role. They can be compared.  Modules communicate distinct ideas.

Every content module should have a specific role or purpose. The role will define:

• What kind of information or message is communicated
• What benefit the content consumer will get from that module (for example, locating information, sparking interest, promoting understanding, etc.)
• How the module fits into the larger body of content being developed and presented

Modules can be concise, broad, or deep in their focus. Modules will not be the same size. Different modules will address varying levels of detail, depending on their role. They will vary in their breadth (the scope of what they address) and depth (the amount of detail they address). 

• Broad modules will have a wide scope with few details.
• Deep modules will have a tightly focused scope with more details. 
• Concise modules will be narrow in focus and provide only a few details.

The role and size of the module will reflect what users want to know at a specific time. Sometimes they want shorter, more general information. Other times they want deeper details.

Structure your content according to how much detail you need to convey. Plan modules around how users will encounter your content, such as what they need to know first and what they expect to find out later. The benefit of modules is that all the details don’t need to be presented at once.

Tailor the detail you offer to match the user’s priorities. The amount of detail you provide and when you offer it should reflect the user’s priorities.

You can think of these priorities as a content hierarchy, with the most important information or message needing to be seen first and the less important information and messages being noticed later. Important information or messages must be noticed and not overlooked. This content often will be shorter in length so that users can scan and process it quickly.

Module size	Position in hierarchy	Purpose	Examples of module
Small (a statement or a sentence)	Top – what’s seen first	Relevance: attention or action	Headings and titles Links Calls to action Button text Short descriptions Alerts and announcement notifications Offer available Nut paragraphs (what’s at stake) Clickable banners Pitch or promise of a benefit
Medium (a single paragraph or combinations of images and data)	Middle – what may be seen after seeing the top	Building interest	Lists of what’s included or available Paragraph statement Relevant example Explanatory illustration Summaries Overviews Product profile Primary message Value proposition Description of problem
Large (multiple paragraphs or more detailed expositions)	Bottom – what will be viewed in detail	Building understanding and answering specific questions	Detailed description Secondary messages Description of solution Instructions Answers to FAQs

The content’s hierarchy reflects how the user prioritizes various modules rather than indicating the visual layout of the content. Often the most important information will be larger than other content, but not always. The development of modular content is independent (decoupled) from the presentational layout in the user interface.

The size and role of the modules will determine their connections. Both the size of a module and its role will influence how the modules can be connected to one another. 

Modules with the same role (“same-role modules”) can sometimes be grouped together to allow their comparison or to enumerate a certain kind of detail. Same-role modules can also be presented as alternative options to users. For example, you can create a list of headings that users can scan and compare, so they can decide which one seems most interesting to them to look at in more detail.

Different-role modules can be grouped together to provide a complete item. They may not need to be presented together at the same time because people won’t necessarily want or need all the details of the offer at once. But as a suite, they offer a complete communication concept. For example, a descriptive heading for a product can be combined with a product profile and with a more detailed explanation of product features and capabilities.  Users may “drill down” to get more details at different stages of their research about products.

Modules will use distinct writing styles. Both the module’s role and detail will influence how the content is written. Each kind of module (modules that share a defined role) should follow a consistent writing style. Different modules will follow a distinct writing style, for example:

• A minimalistic, declarative style that’s to the point (concise)
• An inspiring style that encourages exploration (broad)
• Precise wording that provides concrete details about dates and things in order to answer specific questions (deep)

Depending on the role of the module, the style guidance could extend to sentence construction and preferred terminology. We’ll look at some examples shortly.

Well-crafted modular content writing takes some effort but provides numerous benefits. Modules can make content:

• Easy for readers to scan and digest
• Reusable in multiple contexts
• Understandable on their own without additional context
• Relatable to other modules
• Durable, not requiring revision often, and easy to revise when necessary

Defining, writing, and connecting modular content: tips and best practices

Now that we have reviewed the principles of modular content, let’s look at modular content practices.

Content teams should write in a consistent manner where various modules fit together cohesively.  

Defining modules

Best practice: Keep modules simple conceptually. A tight focus will allow modules to be more reusable.

• Address one core idea or topic only (keeping all the details relevant)
• Include essential information about the topic
• Exclude any information or messages that touch on other details or themes
• Use simple sentence structure

Best practice: Create “standalone” content modules that aren’t dependent on their context to understand. Aim to make each module self-explanatory.

• Use precise wording to avoid ambiguity and use terms that are self-descriptive or are already familiar to readers where possible.
• When introducing less-familiar terms, assume the reader is seeing the wording for the first time.
• Don’t count on the user having read an earlier reference to something you are talking about.
• Don’t use abbreviations that will need to be explained elsewhere.

Best practice: Where possible, make same-role modules “sequence-independent.” If the content relates to an explanation or instructions, consider how users may have a different starting point or entry point. For example, instructions about updating account information will repeat many of the instructions used for creating an account, but the entry point will be further in the process.

• Don’t assume that modules will be read in a specific order since they may be delivered in various orders depending on the context in which they are used.
• Don’t assume that several modules will be read at the same time – the reader may interact with the modules at a different point in time, possibly in different channels.
• Avoid referential phrasing such as “next” or ”as previously stated” since the modular content can appear in variable order.
• If the content relates to a step in a process, give the step a name instead of referring to the step by a number.

Writing useful modules

Tip: Plan modules to reflect how users will prioritize the content. It’s common to think about content as having a fixed linear sequence that’s read from beginning to end or from top to bottom. But modular content can be presented in alternate orders, depending on what other content will accompany it and how or when users will access the module.

Tip: With modular content, flows can be personalized. Individual users may see different items, which could be presented in alternative sequences, depending on each user’s intent. For example, if data about their behaviors suggests they seem ready to begin a process, they won’t need to see introductory items that would be shown to those who haven’t shown such readiness.

Modular content allows information and messages to be treated as ingredients in a recipe. When a customer shows a particular intent, the company can offer a set of modular items that best fits what the customer might be looking for.

Best practice: Mention key details in headings to provide a preview. Use headings as signposts:

• Show what is important with relevant keywords that the audience will recognize
• Show why the information is important by using key phrases relating to benefits (what the content answers or accomplishes)
• Headings should focus on the reader rather than on your organization
• Headings should be differentiated, so that if they appear together in a list, users will understand how they differ

Best practice: Aim to write future-proof content that doesn’t require updating. While no content can be entirely future-proof, content phrasing can influence how durable the module will be.

• Avoid phrases such as “next month” that can quickly become dated
• Avoid generic temporal references such as “recently” or ”soon” since the modular content may be used in different contexts and at different times, rendering the meaning of these phrases ambiguous
• Try to avoid transitory phrasing, such as “ongoing”, “in process”, or “expected”, since such wording can become dated
• Try to make permanent statements that refer to a specific time
• Specify actual dates or durations when they are required. 

Tip: Adopt parallelism in how you construct phrases. Using consistent sentence patterns will make the content more modular since the pieces will flow together when the wording follows a pattern. It will help teams maintain consistency of voice.

Directive content elements	Common word patterns
Navigation headings	Noun Adjective + Noun
Task choices in a menu	Verb Verb + Object
Options in list	Noun Adjective + Noun Verb + Object
Conditional (If – then) message or instruction	Verb + Object, followed by (Subject) + Verb + Object
Feedback	Subject + Verb + Object
Instruction	Verb + Object Subject + Verb + Object
Calls-to-action	Verb Verb + Noun

Connecting modules

You’ll want to create modules that can connect to other information readily. Modules that connect will be:

• Durable because they can be used for a long time without needing revision
• Flexible because they can be reused with many other modules, not just one

Tip: Separate content that is persistent from content that will change.

Broad statements should be simple and not need to change, even if the details do. Examples of broad statements include:

• Overviews
• Most important idea
• General eligibility statements, such as meeting one or all of certain criteria

Group related (same-role) content together so that it can be updated in one place.

Tip: Build a durable gateway into more detailed content. What users first notice can have a critical impact on what they see later. In small modules, space constraints and limited attention mean that every word must work hard, making them harder to write. Try to develop effective phrases that you won’t need to rewrite. Aim to keep this layer stable as much as possible but don’t be afraid to optimize the wording (by testing alternatives) when first developing the module.

Examples of summary gateway elements include

• Lead-in paragraphs providing an overview of what is common to a list or other details that follow: they synthesize the contents
• Synthesizing labels for lists or groups of content items (for example, British detective movies from the 1980s)

Tip: Common patterns to connect modules

Modules can be combined in various ways to highlight different communication goals.

Communication goal	First module	Subsequent modules
Example to illustrate the broader issue	Module with an interesting or relevant example	Module providing context (broader description of what that detail illustrates)
Establishing relevance	Module explaining context (what you’ll be doing, what’s going on)	Modules explaining the specifics
Showing causality	Module describing situation	Module describing an outcome
What to do	Module describing a status	Modules providing advice or options

Developing modularity in your content

For writers who are accustomed to writing webpages, the shift to modular content can require a change in mindset. Writers will need to think more about the context: how different users will encounter messages and information over time in various channels. Collaborating with UX teams who are defining customer journeys is an ideal way to understand what pieces of content customers will need at different points.

As you survey various customer journeys, common patterns will emerge. These patterns will suggest modules that will be useful to create since they can be reused. Start developing recipes for what content to offer in different situations. 

Identify situations where the same content can be useful for different scenarios. Perhaps, your company has introduced a new feature or service. Modules relating to that could be useful in a product tour for prospective customers, a new customer onboarding sequence, or a feature announcement to existing customers.

By following a modular approach, the content you develop will have a bigger impact.