Designing Content: How to Approach Document Design in Technical Writing

This guest blog post was written by Philip Cogavin, a certified MadCap Advanced Developer and MadCap Flare consultant. He is a director and senior technical writer with The Docs Team, specializing in converting legacy content to MadCap Flare.

Technical writing involves so much more than writing a grammatically correct sentence. In fact, all genres of writing involve some aspect of design. Technical writers don’t just write, we design with words. And what is design but the intentional structuring of elements, whether visual or textual, to create the most beneficial, functional, and aesthetic object or body of text. Whether its function is to be practical or thought provoking… well designed content has an intended audience and goal. 

Most experienced writers have learned to implicitly apply design principles when writing. But for those new to writing or for those who manage a writing team, but have no experience writing, design needs to be more explicitly approached. 

In this article, we’ll explore many of the technical documentation and visual elements in effective document design, and we’ll touch on how intentional design will benefit both you and your document’s intended audience.

Audience

Good design always starts with knowing your audience, their needs, and their journeys. Knowing how they work and any limitations they might have is critical to their overall user experience. There is no point in publishing a public help center that is accessed from the internet if the audience works in a highly secure environment without internet access. You’ll need to figure out what type of output best suits them. 

Output Types

Each output type has its own pros and cons. Depending on your specific circumstance one type might work best, or you might need several different output types. Many digital tools and resources, such as an electronics part catalog, now have a mobile and web version, and there are multiple types and sizes of devices to display content on. Most products don’t start with multiple versions so it’s easy to make the mistake of designing for just one output type initially. Keep the future in mind when designing, and plan for all possible output types. It’s a lot easier to achieve this flexibility if you choose a content development tool that automatically allows for this.

For example, MadCap Flare provides the ability to output the same content to different output types, including responsive web, print, desktop, and mobile content. MadCap Flare achieves this through the modular use of targets, reuse of tables of contents, and out-of-box skins. You can focus on writing the content and leave the complexity of designing for different outputs to MadCap Flare.

Read More: Best Practices for Responsive Content

Different Versions of the Same Content

Another challenge that good design can overcome is the need to create similar but different versions of the same content. Products can have tiered features or work on different platforms causing you to have to deliver multiple outputs. Being able to modularize and manipulate which content is included or excluded requires forethought when designing single-sourced content. Topic-based writing, conditionalizing, and using variables enable you to write once and publish in various formats.  

For example, MadCap Flare allows you to reuse content by building different TOCs, conditionalizing out some elements, and assigning different variables from a set of variables.

Desktop or Mobile Layouts

For content delivered via the Web, you can’t be sure whether the user will read it on a desktop or on a mobile device. You don’t want to inconvenience them by making them choose which document that will display better on their device. It’s a better user experience if your content can automatically detect the type of device and adjust. Mobile devices clearly have a smaller display surface, and if you use the right technology your content can adjust. But for the best experience it’s better if you design for both a desktop and a mobile surface. Layouts will determine the look of your content and seamlessly adjust your content dynamically.

For example, MadCap Flare uses mediums and media queries in the stylesheet to configure styles that come into effect when the user’s viewport is a certain width, which is a proxy for the type of device they use. MadCap Flare’s HTML5 templates are configured to invoke the “mobile” medium for mobile phones when the content is displayed in a window less than 767 pixels wide.

Navigation

An effective navigation structure can act as a map for users to help them find their way through your site. Good documentation needs an organizational structure that guides users from beginner topics to more advanced material in an order that mirrors how people learn. For example, if you expect new users to be unfamiliar with your product’s advanced functions, don’t lead off with information about those capabilities.

Navigation can also work to educate users about the different aspects of the product. You might have several types of users use your help site. You can create a happy path for each role by designing a landing page with navigation for each path. You can segment reference, conceptual, or task content and the user can choose which type of content they want to use.

For example, MadCap Flare allows you to create customized landing pages using HTML code and you can choose from a list of pre-design skins each with 

templates for print, online, desktop, and mobile content. Some come pre-installed and are available for use during trial-mode. Others are available to download directly from MadCap Software’s website. They all offer a solid foundation to help you produce customized modern layouts and navigation. 

These default templates allow you to quickly build your document and test the navigation and decide whether a top-navigation or side-navigation layout is better. MadCap Flare makes this quick and easy to do by providing skin templates for both navigation types. By switching between the two, and rebuilding the output in the HTML5 target, both can be compared easily.

Shared Templates and Styles

Consistency is important in good design, especially in DITA technical writing. You’ll want all your writers to use the same page design, layouts, styles, color schemes, etc. Managing this consistency can be a big challenge though if you don’t build it into your design process. Styles change or get added and they all have to get disseminated to the whole team. It can be time consuming making style changes and ensuring everyone is using them in the correct way. With a shared project template and style sheet (CSS), stored in a repository like GIT and linked to import into all existing projects, updating and managing changes becomes a breeze.

For example, because MadCap project files and content files are all XML-based you can easily manage any file via a repository. You can version, merge, and back up files, and share updates easily.

Searchability

We've all been there—you search for something, and either no results appear or so many that it is impossible to find the one you are looking for. There are several ways to make your help site more search friendly and help your users to find the content they need more easily using a search. 

Some features within MadCap Flare that help improve the search experience of your users are: 

• Custom Descriptions - These are concise summaries of the content of the topic. Best kept to less than 155 characters, they are used in search results for HTML5 outputs, and are searchable. When properly used, they improve the findability of the content and make it easier for users to choose the correct search result. Using these in MadCap Flare is as simple as adding text to the Description field of the Topic Properties. The text is stored in the <head> tag of the topic file. 
  
• Index Keywords - While indexes per se are mostly used with print or pdf output, index keywords are targeted in search results. This makes them a helpful tool to improve search results. For instance, inserting “motor bike” as a keyword in a topic about “motorbike” will aid the search as synonyms are not multi-word phrases. MadCap Flare makes it easy to insert a keyword into a <h1> tag or in the body text. Using its <MadCap:keyword term="Keyword" /> tag, the keywords can be placed where they are most likely to improve search performance. 
  
• Synonyms - Synonyms are useful when you want to improve search results for equivalent terms. Using “motorbike” = ” scooter” will result in search results showing topics that include either motorbike or scooter. Bear in mind also the tip about using index keywords for multi-word phrases. 

To use synonyms within a MadCap Flare project, you can add a synonym file to the project. The file is stored in the Project>Advanced folder. The file supports Directional and Groups. Directional is a one-to-one relationship while synonym groups allow several alternative words to be grouped together, for example “bicycle = tricycle = bike = trike”.

Design for Localization

If your product has a global reach, chances are you need to localize your content. Localization can be costly and time consuming. However, there are some design strategies to reduce both. The least amount of content you send out to the localizer the better. Design your content to be modular and topic-based to reduce the amount of content that needs to be sent out to the localizer. For example, using MadCap’s topic files, you only need to send the specific files you changed to the localizer instead of a whole document. If you have standard paragraphs or content, it only needs to be localized once if you contain it in a snippet and reuse it. Once the whole project is localized, going forward you can generate your own localized outputs, which should reduce production costs.

In Conclusion

A well-written, thorough help site can help users understand the benefits of your product and help them to adopt it quickly. You’ve spent a lot of time, energy, and no doubt emotion developing a comprehensive documentation set for your users. Your content deserves to be showcased and used. Don’t let bad or the absence of content design take that away from you. Content design does not equal making your content pretty. It is a vital component to enabling your users to get the best out of your content. Great design enables utility. Many design elements can be easily implemented by using leading technology and great tools, so you can concentrate on designing with words. Additionally, employing technical writing services can ensure that your content not only looks good but also performs well.