Monday, July 13, 2015
The Bleeding Edge was a series of presentations at the annual STC conference (now the Summit). Its goal was to address cutting-edge technologies and methodologies that emerged too close to the conference to be addressed by the standard presentation proposal route. I proposed it after the 1998 conference after hearing comments that there weren’t enough advanced sessions. After approval by then STC-president Mark Hannigan and Assistant to the President Deborah Sauer, I launched the Bleeding Edge in 1999. I ran it from 1999 to 2014 except for a two year hiatus due to some organizational issues in 2008 and 2009.
Bleeding Edge presentations covered JavaHelp coding, XHTML, haptic interfaces (IBM sent a speaker from London, as I recall), the W3C RDF metadata standard, search engine optimization, XSLT, on-demand publishing, and similar topics. My Beyond the Bleeding Edge column in STC Intercom came out of the Bleeding Edge. The Bleeding Edge also spun off a “standards watch” session, with speakers discussing developments in bodies like the W3C and IEEE, and several “standards watch” columns in Intercom.
The Summit organizers decided not to run the Bleeding Edge in 2015 because they thought the Summit’s technical level had risen to the point where the Bleeding Edge was no longer needed. From what I saw of the presentations in Columbus, I agree. Although I’ll miss the Bleeding Edge, its demise is a positive sign for the Summit overall.
My thanks again to Mark Hannigan and Deborah Sauer, and to all the presenters over the years who did such an outstanding job of helping keep STC on the cutting (or “bleeding”) edge.
Sunday, March 22, 2015
New versions of MadCap Flare combine powerful extensions to existing features and new features that go in unexpected and intriguing directions. Flare 11, released on March 17, continues this tradition. In this post, I’ll look at my favorite changes. (There’s far too much new to cover in one post. The What’s New Guide, http://docs.madcapsoftware.com/FlareV11/FlareWhatsNewGuide.pdf, is 350 pages long!)
By way of a brief introduction, I’m certified in Flare and Mimic and do a lot of training and consulting for MadCap so I’m not only a reviewer of Flare but a heavy user.
Extensions to Existing Features
Help authoring often requires authors to perform the same set of steps over and over, such as applying a style to a series of paragraphs. It’s tedious work. Flare authors have been asking for a macros feature that lets them record the steps and play them back with a few clicks. This feature is now available in the Macros group on the Tools ribbon.
To use this feature, click the Record button, name the macro, and do the steps. When finished, click the Stop button (the renamed Record button). Select a macro to run by clicking the Playback button.
This feature is easy to use mechanically, but recording a macro records all your steps – mistakes too. So it’s hard to whip off a new macro on the fly unless it’s a simple one. But once authors get used to having to work carefully, macro creation is pretty simple and very useful.
Word Import Enhancements
Many Word users focus on producing documents that print smoothly, without regard to whether those documents can have a life beyond printing. Because of that, Word documents often have problems that cause trouble when imported into Flare – two in particular, both dealt with in v.11.
- Authors who need to insert a screen shot in a
Word document often just capture the screen and paste it into the document, but
never save the screen as an image file.
This means Flare doesn’t know what to
call the image file on import so it uses a random number for the file name,
such as 0600001.jpg – technically correct but not very helpful.
V. 11 partly fixes this. It names the pasted-in (embedded) image file after the name of the topic in which that image appeared. So Flare calls an embedded image in a Texas topic Texas. jpg, for example. This is a partial solution because if a topic has many embedded images, Flare creates multiple images files with names like Texas.jpg, Texas1.jpg, etc. Authors still have to figure out which image is which, but images being named after the topics that contain them simplifies the search.
- Word authors who create tables usually calculate
the number of rows required, then add a row for the column heads. Flare can
designate a row specifically as a header and format that row using the Header
settings in the Table Stylesheet editor. However, when you import the Word
document into Flare, it has no defined
header row. The solution has been to open Flare’s Table Properties dialog box
and change the Number of Header Rows from 0 to 1. You then have to move the
headings in the original heading row into the new, defined Header row and
delete the old and now empty original header row. Easy but cumbersome.
V. 11 fixes this. It can automatically convert the first row of a Word table to a Flare Header row. You’ll still have to clean up tables that have multi-line headers but single-header row tables will import far more easily. This feature is on the Options tab of the Word Import editor.
I’ll start with a brief review of cross-references for Flare authors who aren’t familiar with them.
Cross-references are similar to hyperlinks but add two benefits.
- They’re “aware of” their target title and change their wording if the title changes. For example, say you create a cross-reference to a topic called Grinder. The cross-reference wording will say ‘See “Grinder”’. If you then change the target topic title to Hoagie, the cross-reference wording automatically updates itself to ‘See “Hoagie”’. This eliminates the manual editing needed if you use traditional hyperlinks to point to a target topic whose title may change.
- They can change their format to a page reference when output to a print format. For example, a hyperlink like ‘See “Grinder”’ is fine as a clickable link in online output or a print output viewed online, such as an on-screen PDF. However, if readers print the PDF, the link obviously doesn’t work – the reader can’t tell what page the link pointed to. This means the reader has to refer to the table of contents or index to locate the target of the reference. But with a cross-reference, the format automatically changes from a hyperlink-style like ‘See”Grinder”’ to a print style like ‘See “Grinder” on page 45’.
So what’s new with cross-references in v. 11?
Cross-reference granularity in prior versions of Flare could be too coarse. For example, a cross-reference might point to a target that wound up on the same page as the link. The result? A reference that said ‘See “Grinder” on page 45’ when the original link was also on page 45. In v.11, the cross-references are more sensitive to the context of the target. For example, if the target is on the same page as the link, the cross-reference wording is ‘See “Grinder” above” or ‘See “Grinder” below’, depending on the target’s position. If the target is on the previous or next page, the wording is ‘See “Grinder” on previous page’. And if the target if further away, the wording is ‘See “Grinder” on page 45’. The result is more realistic.
YouTube and Vimeo Movie Insertion Through the Flare Interface
Flare makes it easy to insert multimedia, such as Flash or HTML5 movies, into topics, but the assumption has usually been that the movies are part of the project. However, more authors use YouTube or Vimeo as movie distribution mechanisms or just want to link to movies from those sites, and v.11 makes it easy to add movie links directly from the web. Authors can either embed a movie in a topic using the Insert > Multimedia > YouTube/Vimeo option, in which case authors can set options like automatically starting a movie when a reader opens the topic, or linking to a movie using the Insert > Hyperlink option, in which case the reader must physically start the movie.
Interesting, Intriguing, and Sometimes Unexpected New Features
In no particular order (they’re all interesting)…
TopNav HTML5 Output
In 1989, starting a help system opened a single pane window that showed the topic. No navigation pane displayed until readers clicked a “Help Topics” button on the “button bar”. That opened the navigation pane in a separate window. Together, the two windows looked like this, navigation on the left, topic on the right:
In 1995, the release of WinHelp 4 introduced connected navigation and content panes that looked like this example (from Microsoft’s HTML Help) and was called the “tri-pane” window.
So the familiar tri-pane has been with us for 20 years. In recent years, however, Flare authors have been asking for a more web-like look. Some authors created it by hand by working directly in the code. In response, MadCap introduced the TopNav HTML5 output. TopNav has many options but the basic effect is to replace the tri-pane with something like this:
TopNav takes the table of contents and places it horizontally along the top of the window. Some layout elements have also been made individually selectable, so authors can create interfaces like this:
The introduction of the TopNav output has several ramifications. Three immediate one are:
- TopNav looks cool but may not work for projects that have many level 1 TOC headings because too many headings will visually clutter the TopNav output.
- TopNav adds many skin options. Using those options calls for more deliberate planning than the traditional tri-pane.
- By breaking away from the traditional, documentation-related tri-pane look, TopNav may allow technical communicators to move into new publishing areas beyond traditional help.
By offering an immediate change in how we design online help and documentation, I consider TopNav to be one of the most meaningful new features in v.11.
For some companies that create Word-based documentation and just need to put it online, Flare may be over-powered. In response, MadCap bought GrapeCity’s Doc-To_Help authoring tool in January. The idea was that authors who didn’t need Flare’s power could use Doc-To-Help instead. However, if those authors decide that they need more power, they can import the Doc-To-Help project into Flare.
U3D 3D Model Import
If your documentation contains engineering drawings, your engineers can save the drawings in Universal 3D (U3D) format. You can then insert the U3D files in browser-based and PDF outputs. Users can then click on the images and rotate them or zoom in and out. (To try it, go to page 173 of the What’s New Guide (http://docs.madcapsoftware.com/FlareV11/FlareWhatsNewGuide.pdf), click on the image in the example, and drag to rotate the image or use your mouse wheel to expand or shrink it.)
Finally, the unexpected – augmented reality. Unlike virtual reality, which takes users into a new reality like a game, augmented reality keeps users in this world but adds a functional layer when users view that world on a mobile device. Augmented reality seems to be most commonly thought of in terms of marketing. For example, Starbuck’s Cup Magic has let smartphone users scan specially imprinted cups that invoke an augmented reality layer atop the cup image. The image below, from www.interactivity.la, shows a Christmas cup that, when scanned, displays the singers on the smartphone screen.
Augmented reality goes beyond marketing. For example, the Theodolite app from Hunter Research and Technology (http://hunter.pairsite.com/theodolite/) superimposes compass, GPS, map, rangefinder, inclinometer, and other data onto a scene viewed on an iPhone screen, as shown below:
When would Flare authors use augmented reality? It’s hard to say. The idea is so new to tech comm that it allows functions we may never have thought of. One idea – field service information superimposed over the image of a machine being serviced.
And I haven’t discussed a whole range of other features such as:
- Customizable keyboard shortcuts, a boon to accelerator key users.
- Git integration, extending Flare’s version control system support.
- Advanced page layout control, allowing very complex layouts for print output.
- An image positioning feature that lets authors control how images fit within text without having to work with float properties in a CSS.
- A global spelling dictionary that can be shared across multiple projects.
- Building multiple targets in the background while continuing to work in the foreground.
- And many more…
Between the extension of existing features and the inclusion of some unexpected new ones, Flare 11 is a major advance. I’m very impressed.
About the Author
Neil is an internationally known consultant, strategist, trainer, and developer for online content in forms ranging from online help to apps. He helps clients design content, select outputs, understand coding, and select and learn authoring tools. To do this, he brings decades of experience in tech comm, with 30 years in a wide range of online formats and tools. (He created the second and third commercial ebooks ever released, for MS-DOS 2.1 and Lotus 1-2-3 2.01 in 1987.) He also spent four years as an industry representative to the WorldWide Web Consortium in the 2000s.
Neil is certified by MadCap Software in Flare and Mimic, and by various other vendors. He is the author of “Advanced Features of MadCap Flare 10” (and earlier versions) and “Creating Mobile Apps Without Coding”, mobile app creation for non-programmers.
Neil writes columns and articles for various professional journals and is a popular speaker at professional conferences. In what passes for his spare time, he builds telescopes, cooks southern barbecue, and is using computer simulators to recreate a lost career as a US Navy fighter pilot. You can contact Neil at firstname.lastname@example.org or follow him on LinkedIn: https://www.linkedin.com/pub/neil-perlin, on Facebook at facebook.com/neil.perlin.7, and on Twitter at @NeilEric.