Select Page

For all the effort that we place on writing good documentation, it is easy to overlook the environment in which customers read our documents.

Where and how they read matters just as much as what we write.

Even the smallest design choice in this environment can have a significant impact on the reader’s experience.

The Details that Distract

Have you ever watched a home design show where the potential buyer cannot buy a home because of the paint color in the kitchen? If you have, you understand how silly it looks from the TV viewer’s perspective.

“Why can’t they see past paint color?”

Because that little detail distracts the buyer. It prevents them from seeing the value of the house as a home.

In the same way, a little detail such as the navigation menu in your portal might distract your customer or prospect and prevent them from seeing the value of your product.

This customer may return to a search engine and try to find the information elsewhere. At that moment, your organization loses a valuable interaction. This lost interaction hurts in two ways; you lose a little bit of credibility in the mind of the individual, and you lose valuable analytics data to help you better understand your customer.

With this mindset, we developed our new documentation portal. It is intended to model the best practices in document delivery; to remove the distractions and focus on a seamless user experience.

First Page Impressions

It all starts with the home page. Within the first few seconds, the reader will assess the usability of the document site. This assessment will determine their level of commitment to searching through the site. You can measure this commitment by the bounce rate for your site’s first page. A high bounce rate likely indicates one of two things:

  • They don’t believe the site will provide the answers they seek
  • They believe the site might have the answers they seek, but the same information can be found elsewhere with less time or difficulty

In both of these cases, the response is twofold.

  • Provide a first impression that establishes the scope of knowledge available
  • Provide a comfortable and navigable visual experience that doesn’t alienate

Rather than allow a visitor to become confused or frustrated with their first impression, we built our portal specifically to maximize the user’s first interaction. We developed a homepage that is clear, concise, and navigable. These three attributes dictate the quality of the experience a visitor will have on our website.

Why these three attributes? It’s important to remember that the visitors to a documentation portal have specific questions and they want answers. Their utilitarian mindset means that the documentation portal should clearly and concisely indicate how to navigate to their answers. Distracting elements that detract from these three attributes will only frustrate and drive away visitors.

In order to help our portal visitors as much as possible, we built our portal with both design and language that was clear, concise, and navigable.

The clarity of the design is most defined through the central six buttons on the page. The blue starkly contrasts the white background and catches the visitors attention immediately. This design also contributes the navigability of the page. Due to the color and placement of the buttons, the visitor will naturally look towards those buttons and quickly identify how to proceed to the desired information.

The page’s concision is demonstrated by the descriptions for each button. Generally, descriptions are helpful, but tediously long descriptions are not. None of the button descriptions exceed four words.

The result of these factors is a homepage that is helpful for visitors on the desktop or mobile devices. As we’ll see, the principles used to build this first page extend throughout the rest of the portal, starting with the sitewide navigation.

Common Sense Navigation

On the home page, the user selects an appropriate button based on their search. The user is then brought to a common-sense page design with links to further information within the topic. The length of these descriptions is purposefully brief. Each description is just long enough to tell the reader the contents without any unnecessary exposition.

On the left side is the navigation tree. Many sites will implement an ever-expanding tree. We believe this is a mistake from a usability perspective. While it might make sense logically, the result is an unfriendly user interface. The ever-expanding tree will either become cramped and unappealing to navigate or the side panel will have to use sideways scrolling to accommodate the text. This experience slows down the user. The table of contents becomes harder to mentally digest and may require excessive vertical and horizontal scrolling. This navigation issue is only exacerbated on mobile devices.

Instead of an ever-expanding tree, we limited our navigation tree to two levels. At the bottom layer of each tree, there are still content divisions, but users navigate these divisions via a topic navigation in the right-top-corner of the screen.

This approach allows customers to identify where they are within a page’s hierarchy at any given time on our website. We constructed the site design in a way that if someone landed on a topic via search, they would immediately identify their location within the portal’s hierarchy.


We all rely on search. But a poor search experience can quickly sour what was otherwise a pleasant website experience.

We have identified and focused on a few primary components for a good search experience:

  • Context for a Match
    Yellow highlights indicate precisely the location of the word or phrase they searched within the context of a topic.
  • Breadcrumbs
    Users see at the top of each search result, where that topic fits within the hierarchy of the portal. This visibility means they will be able to quickly identify that their search result is within a relevant category.
  • Scannable Titles
    Readers only need a split-second to scan through a list of titles and find the right one.
  • Refined Search
    If the search term is ubiquitous within the industry, our search utilizes metadata to better filter the results. This feature will continue to expand as we include more metadata within the search functionality.
  • Readability
    The easyDITA documentation search results are comfortably spaced, appropriately sized, and readable.

Adjacent to each search result is an eye icon. When clicked, a Lightbox, pop-out preview is displayed. This feature allows users to see the entire topic without leaving the search results.

Rather than going back and forth between tabs or pages, they can bring up the preview for any page, find the right one, and navigate there.

For Writers

We built our portal directly on the easyDITA stack. Consequently, the content we author in easyDITA is ready to deploy immediately. Typical portal authoring processes involve multiple steps or plugins because they are two distinct systems. With easyDITA, the authoring and the portal publishing are tools within the same system. This unification magnifies the potency of our streamlined publishing.

From authoring to publishing, the process is streamlined and this includes previewing our writing. We preview the content in a secure, staging environment that mirrors the actual published site.

Another benefit of working within a DITA component content management system is the nuanced level of control over the breadth and targeting of the output. Within our portal, we can provide users with context-sensitive help and direct them to specific pages in the portal based on the issues they’re troubleshooting. Additionally, our portal supports DITAVals, which enable us to conditionalize the content presented in the portal based on the audience.

The Details that Connect

Throughout the development of our easyDITA portal, we identified the details that distract and replaced them with details that connect our readers and our writers in a seamless way.

The easyDITA portal is the fastest and easiest way we can publish content for our users. By providing a model of best practice and simplicity in a way that replicable, we are making strides towards a more communicative, helpful relationship between readers and writers across the industry.

See the portal for yourself.

If you would like to join us on this journey of clear, concise, and navigable documentation delivery, contact us or leave a comment.

A better way to manage technical documents

John Baker

John Baker is a Content Marketing Manager for easyDITA, a DITA Component Content Management System based in Rochester, NY. He works to produce articles, webinars, white papers, and case studies.
Free 30-Day Trial