The second article in a five-part series, Paul Stoecklein has headed up the documentation department at MadCap Software since its inception, overseeing the development and publication of all online Help systems, PDF manuals, and video tutorials for all applications in the MadCap product family.

One of my pet peeves (aside from the phrase “pet peeve”) is when you open an online Help topic and you have to scroll through a whoooooooole bunch of text to find what you need.

Don’t get me wrong. I have some long topics. Sometimes there’s no way to get around that. I’d rather have too much information in a topic than not enough. I’d also rather look in one long topic for related information than in 25 separate, but smaller, topics. But with only flat text in a long topic, it can be overwhelming and really difficult to locate stuff.

That’s why I’m a huge fan of drop-downs, which let you condense a particularly long topic into multiple sections. Rather than seeing a massive sea of text, users are faced with a little bit of text and a handful of links that open the rest of the content. It’s much less intimidating, and much easier to navigate.

Keep in mind that some people prefer togglers over drop-downs. That’s cool. Just use what works best for you. I simply prefer drop-downs.

Using Drop-Downs in Your Documentation

As the following image shows, when you first open topic in the output, you’re looking at it from a bird’s-eye view.

ConditionTags If you want to read from beginning to end, that’s fine. But if you want to quickly locate something in the middle, or toward the bottom of the topic, this is a much easier way to do it.

Not only that, but I often have nested drop-downs (i.e., drop-downs within drop-downs), depending on how much information each drop-down contains. Sometimes it goes to four levels deep.

TableStylesheets

In order to make nested drop-downs easier to read and distinguish from other drop-downs, I use classes on the MadCap|dropDown style. With my style classes, I give the deeper (2nd, 3rd, and 4th) levels a light background color, and I indent each level.

Stylesheet Editor:

StyleseheetEditor

Internal Text Editor:

InternalEditor

I don’t apply a style to my first-level drop-downs, but when I create a drop-down at the second, third, or fourth level, I right-click on the MadCap:dropDown structure bar, and I select the appropriate style class.

Dropdown

And by the way, drop-downs also help me with the issue of advanced users versus beginners. I’d love to produce entirely separate documentation sets for users with different levels of experience, but I simply don’t have time. So I rely on drop-downs to help me.

For example, I might have a step in a procedure, and maybe the text in that step is all that experienced users need. But then I’ll add an example after that text for the benefit of newer users. By putting the example within a drop-down, users can decide for themselves if they want to open it. Experienced users can skip it and get on with their lives. Newer users can open it to get the extra help they need.

Example

Any experienced technical writer knows that the volume of documentation you create can easily get away from you. That’s why drop-downs can be such a great tool. They help to keep your online topics organized and easier to read, and they help prevent your readers from throwing their hands in the air and saying, “Oh I give up! I think I’ll just call tech support.”

If you have any questions about best practices for including examples in your MadCap Flare projects, please feel free to reach out to me on Facebook or on Twitter at @MadCapDocTeam.

About The Author

Paul Stoecklein

About Paul Stoecklein

Paul Stoecklein has over 20 years of experience as a writer, editor, and documentation specialist. In that time, he has worked for a wide range of companies, including Anheuser-Busch, Edward Jones, and eHelp Corporation. Since the formation of MadCap Software in early 2005, Paul has headed its documentation department.

Last Modified: January 15, 2016

This entry was posted in MadCap Flare, Tech Comm, Tips & Tricks. Bookmark the permalink.

Comments

  • Fer O'Neil February 10, 2016 at 8:45 AM

    I love drop-downs as well! However, when we started to look at using them in our documentation (after seeing how well we liked them in much of MS’s updated documentation), we first wanted to do a little user research. For us (technical writers and our tech support agents), the drop-downs made skimming much easier when we were looking at the content–but did that help our users resolve their issues? We wanted to be sure before moving forward. Unfortunately, our cursory user testing found that users did not prefer to “hide” the content in the drop-down containers — for whatever reason, they preferred to have all the content laid out on the page, no matter how long it was — I think this is because as a user troubleshoots an issue, they want to be sure they are seeing all the steps (and to gauge how much cognitive resources will be involved). Of course we would like to do more robust testing, with more users, but based on the preliminary results we do have, we decided to be very cautious with implementing drop-downs wholesale. I advise others to be equally as cautious and test any changes such as this before altering an entire information architecture structure. I would also love to hear from others who have tested these with their users, with success, and maybe we (as technical writers) can share this knowledge to see where this is beneficial (e.g., by industry, by content type, etc.). Great blog series btw! -Fer

  • Paul Stoecklein Paul Stoecklein February 11, 2016 at 10:04 AM

    Thanks for the great feedback, Fer! I also would be really interested to know about the experiences of others. I happen to prefer drop-downs myself when reading a long topic, but hey, I’m not everyone.

  • Michele February 29, 2016 at 12:55 AM

    We love to use drop-downs in our online-help, mainly for procedure pages.
    It’s really easy to implement this useful functionality in a Flare project!

  • J'Ro March 21, 2016 at 1:07 AM

    Funny that your pet peeve is to scroll through content. What I dislike intensely about the Help in MadCap is how you overuse progressive disclosure. Oftentimes some expanding text reveals only a sentence, and the entire experience is one of peek-a-boo and forcing the user to hide instead of scan. Readers who are reading to do will: scan (to find likely areas to read), then skim and skip through the text. Your approach goes to excess and makes scanning impossible. A further annoyance is that the text jumps, on expand, so it’s a thoroughly jarring experience.

    • J'Ro March 21, 2016 at 1:11 AM

      By “forcing the user to hide” I meant “forcing the user to deal with hidden content.”

    • Paul Stoecklein Paul Stoecklein March 21, 2016 at 1:35 PM

      Thanks for the feedback. And believe it or not, I agree with you, to an extent. There are definitely places where we have them and I wish we did not. For example, when there is a handful of list items with just a bit of text after each one, and they each are in expanding text. Those are usually pretty old instances, and when I find them I shake my head and unbind them because I think it’s overkill. I tell my writers to use their best judgment on each case, and to make sure there is enough substance in a drop-down or expanding text effect so that people aren’t having to over-click. In some places I know we’ve overdone it… but not everywhere. I think there is balance to everything. Sometimes I’ll actually get conflicting requests from readers, including on this very subject (e.g., Reader A wants more expanding text, while Reader B doesn’t want any). I don’t think drop-downs and expanding text should be on everything, but I also don’t think they should be nowhere; I try to find that place in the middle where it feels right. I definitely won’t please everyone, but I try to accommodate those who want some of the longer content collapsed, while not overdoing it. And I figure that those who don’t want any of the content in drop-downs or expanding text can just click the expand all button at the top of each topic to avoid it altogether.

Have Something to Say?

Your email address will not be published. Required fields are marked *