MadCap Flare: generating help system for portfolio

A good help system portfolio showcases our smashing expertise better than a thousand words. But it’s very easy to deliver a portfoolio if you’re unaware of all pinpricks of MadCap Flare 10 or another help authoring tool (HAT) that you’re using.

This and more below, in less than a thousand words.

There is nothing like looking if you want to find something

You may have a great ‘there and back again’ success story laid out neatly in your resume, but it is the palpable artifact that proves your expertise. Been there, done that, got an arkenstone.

The web is teeming with all sorts of useful portfolio checklists and guidelines, but if you want to reap the success before you’re Gandalf’s age, go the practical way ‒ browse through a couple of portfolios and consider them from the perspective of the customer.

All good stories deserve embellishment

I’m willing to bet my second breakfast that you’ll back me on this conclusion.

Healthy share of portfolio success depends on how you gift-wrap and deliver it.

Tips:

  1. Submit your portfolio interactive ‒ include a clickable sample of the help system rather than a screenshot of how it looks.
  2. Make the portfolio conveniently accessible ‒ for example, keep it hosted on a website or cloud server, granting your customer access to the output file only.
    Surely, it would be easier to send the entire archived output folder to the customer, but they won’t be jumping for joy when digging their way through to the output file.
    Besides, you’re facing a bigger risk of putting out sensitive data.
  3. Pay attention to the topic architecture and design, ensuring that the help system looks attractive from the get-go.
    As an external evaluator, the customer is unable to appreciate information correctness or thoroughness, so they will evaluate all content purely from the visual perspective:

    • Visually distinguishable information chunks (abstract, notes, procedure heading, drop-down text).
    • Graphical presentation of the workflow along with legend or accompanying text.
    • Neat procedure steps.
    • Clean textual content not overcluttered by hyperlinks, notes, or other attention getters.

Attractive topic architecture and design

The last step is to ensure that your portfolio keeps to non-disclosure agreement (NDA) and information security.

It's not as bad as you feared but not as good as you hoped

It so happens that in the outsourcing world, we are often bound by NDA to not disclose our customer’s identity.

So, when adding a document sample to your portfolio, you need to do some housekeeping. And somewhere along the way, it got more complicated than a quick find-and-replace of the customer/product name in the topics.

Follow these steps to clean all sensitive data from your MadCap Flare help system.

Target

If you have multiple targets in your project, their data might slip into the output folder of the target used for your portfolio. That way, you’re running into risk of output files that compromise your customer.

To avoid this, in the advanced settings of your target, configure MadCap Flare to exclude unrelated content.

Exclude content not linked directly or indirectly from the target

Startup topic/master page/skin

Make sure you clear customer logo, contact details, copyright info, and hyperlinks to other content that is not intended for your portfolio.

Content explorer

Replace sensitive data (customer name, names of the products and their components, and other) in all file and folder names.
Otherwise, this data may appear in topic path.

Topic path is displayed in search results

This process is much easier if you use variables from the start.

Searchability

Another problem is that even the topics absent from Contents may show up in search results.

Search results show topics that were not included into the Contents

In MadCap Flare, there is a way to avoid this, but you probably won’t like it. For each topic that is NOT in your Contents, in topic properties, clear the check box in the Searchable area.

Include topic when full-text search database is generated

Glossary and index

Last but not least, check that glossary and index contain no sensitive data, such as names of the products and their components.

That’s about it ‒ you can wrap up your portfolio and retire for a hobbit snack in good conscience. Got any more tips or tricks ‒ don’t be Smaug about them and share!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s