Thursday, November 9, 2017
On November 1, I put up a post about best practices for using MadCap Flare. The post included some tips from Craig Wright of StrayGoat Writing Services , but I didn't include his contact information. Sorry about that.
Craig's web site is https://straygoat.co.uk/.
Wednesday, November 8, 2017
I was asked on LinkedIn whether Flare supported image maps and how to create them. I don't see image maps used much anymore but they can be useful. Flare makes it easy to create them with its built-in image map editor. Here's how:
- Insert your graphic in the topic.
- Right-click on the graphic and select Image Map from the dropdown menu.
- Click on any of the three "New... Mode" buttons on the toolbar and draw the desired shape. To resize a shape, click on and drag one of its drag handles. To move a shape, just drag it. There are various other image options, but the three mode buttons are the core.
- After you create the shape, double-click it. The Area Properties dialog box opens. (It's basically the same as the Hyperlink Properties dialog box.)
- Specify the link parameters like you would for any type of link and you're done.
Wednesday, November 1, 2017
- 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
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.”
“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
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”.
- 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.
- 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.
Monday, October 30, 2017
I don’t see user-generated content replacing traditional online documentation/help but extending it. The documentation/help will still contain stable core content but link to user-generated content in blogs or wikis containing new, changeable content. Technical communicators and user-authors form a virtual team. If you create online documentation/help but don’t link it to your company blogs or wikis, take another look.
Similarly, video and animation have been around for years but not often used because of the costs and required skills. But lower prices and simpler tools are putting video and animation into more hands – e.g. user-generated. It may be “movies” created quickly using tools like Adobe Captivate, TechSmith Camtasia, or MadCap Flare, or from video bloggers. (YouTube may also be a source. You may not find the perfect video there, but there are so many clips about almost any topic that you may find one that’s good enough. The volume of clips provides flexibility, and the material is available quickly, even if the production values may be “dirty”.)
So rather than discount the idea of user-generated content, we should be actively helping to create, organize, use, and distribute it in the first place.
Instead, consider setting up your control files to handle your common needs and ignore or modify other needs that are too difficult or marginal to handle in the control file. For example, you might create a “first-paragraph” style with extra space above for use in hard-copy, but can you replace that style with the “body” style and live with the “good-enough” result?
So the results may lack the perfection that you got by hand-tweaking the material, but you get the good enough, quick-and-dirty convenience of bringing programmatic control to your writing tasks. (Wired made an interesting point about users coming to accept MP3 quality as the standard rather than the higher quality of CD because they used MP3 more and got used to it. As more and more readers get material online, they may come to accept online style quality as the standard.)
Wednesday, October 25, 2017
In my post about Flare 2017 R3 on Nov. 24, I said:
"If you copy the content in this topic, paste it into Word, and generate the readability statistics in Word, you’ll get different results. When I tried it, Word gave a readability of 65.1 and a grade level of 7.0, both still excellent but different from Flare... This may be caused by Flare’s using the same "Flesch Reading Ease” and “Flesch-Kincaid Grade Level” algorithms as Word but with different options enabled."
As it turns out, the problem is not one of having different options enabled in Flare vs. Word but rather the fact that Flare and Word interpret what a "sentence" is somewhat differently. So the feature is still as useful as I said it was in yesterday's post, but the Flare and Word results are not directly comparable.
Tuesday, October 24, 2017
- The Style Inspector on the right tells me that the title uses h1, the font-size is 140%, and so on.
- There are no local style attributes, as indicated by that empty pane at the top.
- I could add local formatting by clicking the + sign in the top pane or an additional property by clicking the + sign in the lower pane.
- I could change the value of one of the properties by clicking the ellipsis to the right of that style.
- I can see what style sheet is controlling this style, here “ipswitch_styles.css” and see the path to that stylesheet by hovering over its name.
- I can add a comment to a style by clicking any property of the style, right-clicking the style itself, and selecting Add Comment. You must click on one of the properties first.
Tuesday, October 10, 2017
“Perfect vs. Good Enough” – Writing Quality in the Online Age
By supporting “good enough” as opposed to “perfect”, isn’t winging it exactly what I am calling for? But it’s not winging it if you write to a standard, just that that standard may call for “good enough.”
Outsourcing is a new competitor. Technical writers are upset over the perceived lower quality of outsourced material, and lost jobs. But consider the business perspective. If outsourced material has 50% of the quality but is written at 25% of the cost, a company may decide it’s a worthwhile tradeoff.
Defining A “Perfect vs. Good Enough” Standard
Tuesday, September 19, 2017
- Defining clear and consistently accepted terminology.
- Demonstrating support for the company's strategic and business direction.
- Dealing with problematic senior management biases.
- Establishing and following standards, metrics, and analytics.
Defining Clear and Consistently Accepted Terminology
- Twenty years ago, and even today, there was confusion over “WebHelp” versus “Web Help”, for example. Because of that confusion, many companies bought the wrong tools, hired the wrong people, or just went off in the wrong direction.
- Today, there’s confusion over the meaning of “mobile”. Is it an app? Responsive online help on a laptop and a mobile device? Something else? I recently consulted at a large manufacturing firm that brought me in to help assess its readiness to go mobile. One result was the discovery that the different divisions had totally different interpretations of the term.
- Information 4.0 promises entirely new levels of terminological confusion. Is “molecular content” the same thing as a topic? What’s “dynamic” content? And so on.
Demonstrated Support for the Company’s Strategic and Business Direction
Dealing with Problematic Senior Management Biases
Standards, Metrics, and Analytics
Wednesday, September 6, 2017
What Does “Mobile” Actually Mean?
How Do We Plan to Go Mobile?
1 – Responsive Output
2 – Converting Online Doc to An App
3 – “True” Apps
What Effects Might Mobile Have on Your Development Practices?
Do Your Business Processes Support Mobile?
Tuesday, September 5, 2017
Tuesday, April 11, 2017
Welcome to MadCap Central
NOTE 2: Since I wrote this article, MadCap has released v. 2017 of Flare, which does not change the interaction with Central, and a new version of Central which adds support for Slack. Central's basic concepts and features remain the same however.
Version Control Features
At this point, you’re using MadCap Central like any version control system.
Upload latest local files to MadCap Central – Click to move any changes made on the author’s local PC to the version of the project in MadCap Central. You’d do this to update the version in MadCap Central with the latest local changes.
Open the MadCap Central portal – Click to open MadCap Central in your browser. You’d do this to quickly access MadCap Central’s project management features.
- MadCap Central is in public beta as of the date of writing this article – mid-December 2016. My experience is that everything is working smoothly but, as in any beta, some oddities may emerge.
- MadCap Software plans to provide a gigabyte of storage for each MadCap Central subscription, shared among the users associated with a subscription. That figure may change depending on the result of the beta.
- MadCap Software hosts MadCap Central, handling all server administration for you and effectively acting like a shadow IT department. This saves you the cost and effort of hosting a version control system yourself. Note that if you have a mandate to use a version control system that’s already in place, you can use MadCap Central in conjunction with other tools like Subversion or Git.