Wednesday, November 1, 2017

More Best Practices for Starting to Work with MadCap Flare - Standards


Flare has so many options that it can be hard to decide where to start, even if you've taken a class and especially if you haven't. New Flare users often just jump in. But this can get you off to an inefficient start, perhaps even a bad start, and create problems that ripple down to later projects.

I recently wrote a post for MadCap’s MadBlog that reviewed best practices for starting to use Flare. (See https://www.madcapsoftware.com/blog/2017/10/12/madcap-flare-best-practices-starting-a-new-project-from-scratch/) I expanded that post into a longer white paper for MadCap. (See https://assets.madcapsoftware.com/white-papers/White_Paper-7_Best_Practices_for_Starting_Your_First_MadCap_Flare_Project.PDF
In this post, I’ll take the topic of best practices further by expanding on the Standards section of the white paper. The original MadBlog post, the white paper, and this blog post are based on twelve years as a certified Flare consultant and trainer and eighteen years of hypertext consulting and training pre-Flare. However, always consider your specific situation before following any suggestions. With that, let's look at the standards issue in more detail.

The more you standardize, the more consistent your projects will be and the less authors will have to guess about what setting to use for a given task or feature. Things you might standardize include:

  • Graphic file formats – Many graphic formats are available today and Flare supports most or all the ones that you’re likely to use. The traditional approach is to use GIF for screen shots and JPG for photos. This works but you’re maintaining two sets of files, GIF and JPG.

    You may find it more efficient to use PNG for all graphics, including those for your print outputs. A PNG’s quality may not be as good as that of an EPS but your users won’t know because they haven’t seen the EPS so they won’t have anything to which to compare the PNG.

  • Conditional build tag usage – Condition tags are the core single sourcing feature but they can go out of control if you don’t set rules for their use. (I’ve talked to two firms this year that used tags with no initial rules about when to insert and how to call them. One company had a project with about 1,000 topics and 1,500 “unruly” tags. The other had about 1,000 topics and 15,000(!) such tags. The result was that new authors couldn’t figure out what tags to include or exclude for a given target and when to add new tags.)

    Creating and inserting tags is flexible – you can apply tags to a character in a topic, a paragraph, an entire topic, a group of topics, a folder, and any other element in a Flare project. And it’s easy – assign a name, pick a color, add an optional comment, and you’re done. In fact, it’s so easy that new authors often gloss over the crucial first step – defining what they’re trying to do and documenting it. So my suggestion is to first decide what you want to do, then define rules for inserting and using the tags, such as the smallest element you can tag. Document this. And test the results to make sure you’re getting what you expect.

  • Variable and snippet usage – Two excellent points from Craig Wright (https://www.straygoat.co.uk).

    “Try to plan your content reuse at an early stage, especially if there are multiple writers involved. It’s no good creating snippets if the other authors aren’t aware of them.”

    and

    “Make sure your snippets are well organized. If authors struggle to find the snippets they need, they may create their own and duplicate existing content.”

    A few comments of my own regarding Craig’s points:

    o   Get all authors involved in the planning early on.
    o   Define the variables and snippets in two groups – project-specific and shared.
    o   Set up a parent/child project structure using the Flare Project Import feature and put shared variables and snippets in the parent project for easy downloading to the child projects.
    o   Let all authors know when a new variable or snippet has been added to the shared sets.
    o   Make sure that all authors know that any changes to shared variables or snippets must be made by the “owner” of those files, not by the individual authors.
    o Make sure that the snippets are clearly named.
  • Index entries – My experience is that traditional indexing is declining among Flare authors, with search taking over. This makes sense since search is easier to implement, but an index can do things that a search can’t. For example, if I refer in a topic to a sandwich made of cold cuts on a tubular loaf of bread as a “sub”, searching for “hoagie” won’t find the topic because the search is looking for the search term in the topic text. But an index lists keywords attached to the topics rather than terms in the topics, so it’s easy to add the keyword “sub”, plus the keyword “hoagie, see sub”, and so on. This makes it more likely that users will find the right topic. (Flare does let you add search synonyms but this can be a tedious job.)

    If you’re going to create indexes, define some rules to make the entries structurally consistent from project to project. Here are a few:

    o   Decide if the verb should use the infinitive (“to print”, then remove the “to”, leaving “print”), or the gerund (“printing”). I prefer the infinitive but that’s up to you.
    o   Decide whether the noun should be plural (“documents”) or singular (“document”).
    o   Decide whether to use sub-entries. For example, the term “BBQ” might be a first-level index entry, with “Carolina”, “Tennessee”, and “Texas” as sub-entries. Note that you could also use those sub-entries as first-level entries – e.g. “Carolina BBQ”, “Tennessee BBQ”, and so on.
    o   Consider using inversing. If you include the first-level entry “print dialog box”, include “dialog box” as a first-level entry with “print” as a sub-entry below it.
  • Hyperlinks vs. cross-references (xrefs) – Hyperlinks have been with us since the beginning of online help but they have two limitations.

    o   The link text doesn’t update if the title of the target topic changes. Let’s say you link the term “sub” in topic A to the “Subs” topic. You then change the title of the “Subs” topic to “Hoagies”. But the link term remains “sub”. You must find and change it by hand. In contract, a cross-referenced term is programmatically linked to the title of the target topic, so changing the target topic’s title automatically changes the link term too.
    o   A hyperlink keeps the format of a hyperlink when you output to print, such as PDF, and the link works if the user is viewing the material on the screen. But when the user prints the material, the link obviously doesn’t work. But a cross-reference will literally change its format from a link style to a page reference – “information about spaniels, see page 225”.
So a cross-reference is a better choice if you generate online and print targets. The limitation is that a cross-reference won’t work if you create a link from a topic in a target to an external file, like a URL or PDF. In that case, you must use hyperlinks. That limitation aside, cross-references are the best and most flexible choice for links.

  • File naming – Setting file naming conventions is, surprisingly, one of the hardest tasks in working with Flare. There are two naming issues, programmatic (thanks to Stephanie M.), and semantic.

    o   Programmatic conventions are straightforward. Use all lower case or mixed case? Can multi-word file names use spaces, use underscores in place of spaces (file_name), or use “Camel Case” (FileName). Check with your IT department.
    o   Semantic naming conventions, to indicate what a file contains, is harder, and you’ll want to involve all the authors in the process. For example, you might decide to name graphic files by the name of the screen followed by the type of screen, such as “Dialog Box.” The result is “Print Dialog Box”, easy to find in a list if you know the name of the screen that you want. Alternatively, you could name graphics by the type of screen followed by the name of the screen, such as “Dialog Box – Print”, easy to find in a list if you know that the desired screen is a dialog box but don’t remember which one.
Two final planning thoughts in addition to documenting your standards, getting trained, joining a user group, and contacting support as discussed in the white paper:

  • Decide what your priority and secondary output targets are. Some features, like togglers, work fine online but not in print. So deciding on your priority target will help guide your selection of Flare features.
  • Decide if mobile is in your future. If it is, note that some features, like popups, don’t work on mobile devices. So knowing if you’re going mobile will also help guide your selection of features. Note that this can apply in other project areas as well, such as making sure that all movies you create using Mimic are in HTML5 format because SWF format won’t display on iOS devices.

Conclusion

I’ll partly repeat what I said at the end of the white paper – Flare is a big powerful tool. If you’re new to it, it may not be obvious what can even be standardized. By following the suggestions in the white paper and here, you’ll help get your Flare work off on a sound footing and help keep it that way.

No comments: