The first 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.

I’ve been writing the documentation for MadCap Flare and MadCap Software’s other products since, well, the beginning. But no matter how long you’ve been using Flare, there are always ways to improve your projects. Even as a longtime user, I find this to be true. In this post, I’ll talk about the first of my five favorite ways to improve a Flare project.

Perhaps my number one rule when writing documentation is that it’s got to have lots of examples. I use examples because I want everyone to come along for the ride, not just the experienced users who might not need the extra information. I want my audience to “get it.”

Using Examples in Your Documentation

Here are a few principles that I like to use when including examples in my projects:

  • If I’m writing about something and I think someone might need a bit more context or story to get it, I add an example, often with multiple images. If I’m not sure an example is needed, I’ll probably add one anyway. I’d rather err on the side of caution.
  • I use unique styling on my examples to make them stand out from the rest of the content and to further illustrate whatever style or concept we’re discussing.
  • Don’t let divs scare you. They’re just containers to hold content. By using a div, you can affect the look of everything inside that container, instead of creating a whole bunch of different styles for each paragraph.

Let’s go through the steps I took to create a few examples in my MadCap Flare project…

In my stylesheet, I selected div and created a class. Mine is named “example.” See the example below.

paulimprove flareproject_image1

Next I styled my div.example class to give it a background color and rounded borders.

Stylesheet Editor:

paul2

Internal Text Editor:

paul3

 

In Flare’s XML Editor I selected content to be included in the example, and I applied my div class to it.

paul4

With the content selected, I opened the Home ribbon, and in the Paragraph group, I clicked this button paulbutton, which lets you apply a group style (such as a div) to a whole collection of content.

paul5

In the dialog that opened, I selected my div.example style class.

paul6

Most of the text in my examples uses the generic p style. But sometimes I’ll apply a different style. For example, I have a style class that I apply to the example heading above to make it stand out.

paul7

As technical writers, we probably think about examples as “nice to have” elements if we get the extra time to add them. But I’ve found that they’re much more important than just icing on the cake. In fact, some people tell me that they go straight to the examples when looking at the documentation. So if you really want to improve your Flare project, there’s no better way to do it than by integrating some good visual examples.

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.

Until next time…

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: November 23, 2015

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

Comments

  • Thomas Böttiger November 23, 2015 at 2:28 PM

    Using examples for quite some time already in online help systems, I recommend putting them inside an expanding text area that can be styled. The advantage is that users do not have to read them if they feel confident enough. Expandable text can be printed as text areas when publishing as PDF, so nothing is lost.

  • Derek Warren December 9, 2015 at 8:53 AM

    Paul, implemented this today! Thanks for a simple and clean solution that also creates value for our customers. While we already have some examples in our content, our own customer research shows us that customers are looking for information in the doc that ties everything together for them. We are a single-sourcing shop and so our content model is designed around reusable topics and snippets. I think the value in this type of model is only overshadowed by the disparate chunks of information it creates. So Examples help to tie things back together for the user. Looking forward to your next installment!

  • Stephanie March 2, 2016 at 11:46 AM

    This was helpful, thank you!

Have Something to Say?

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