Easiest way to add video to your tech comm

A very cheap and easy way to add video – or more honestly: almost video – to your documentation is to use animated gifs. In less formal, less complex settings, that can be totally sufficient.

For example, a translator asked us for the list of Flare topics that correspond to the table of contents. And I want to show other writers how to get such a list out of Flare. It’s a couple of clicks in the TOC editor which can easily be illustrated in an animated gif:

How to export a list of topic names and files names from Flare's table of contents

The gif above was created using the freeware LICECap which records screen movements and mouse-clicks. The 30-second “video” took 5 minutes to throw together, it’s 407 KB large and displays in any web browser without any codecs.

It’s certainly not the most professional way ever devised and there are no use controls whatsoever – but if you just need to illustrate a few clicks, this will let you get the job done quickly and for free!

Oh, and if you’re using Flare, you might have picked up a trick for the TOC editor along the way… 🙂

Advertisements

Optimize MadCap Flare for large projects

MadCap Flare can be slow with large projects and choke sometimes, but there are a few tweaks that can help you to optimize your editing experience and to keep your sanity. By large projects, I mean more than 20,000 topics and snippets, that’s when it gets hairy for me. By contrast, I also work a lot in a project with close to 1,000 topics and snippets and that size is not critical at all for my PC’s performance or my sanity.

All these tips work with Flare 9, and I believe they work with Flare 8, too, but I haven’t checked.

Tweaking performance

There are a few settings which have a big influence on Flare’s performance, especially in large projects. However, consider each one carefully – after all, you may actually need that function…

  • To improve performance in text editing:
    • Uncheck the File > Options > XML Editor > Text Rendering options
    • Disable File > Options > Auto Suggestions
  • To improve performance in file handling:
    • Hide conditional indicators in Content Explorer
    • Apply restrictive filters in the File List, as opposed to displaying most of the files
  • To improve performance of Analyzer:
    • Uncheck the File > Options > Analyzer > Advanced Scan options
    • Set File > Options > Analyzer > Search Limits to 100

Keeping Flare’s “desktop” tidy

Flare’s “desktop” area with its tabs is seductive, because you never notice how many toipcs you have open until you hunt down one. To keep your contents safe and your Flare “desktop” tidy, use these options in File > Options > General:

  • If you don’t need Flare to reopen the same files as in your last session, uncheck Auto-Reload Documents.
  • To minimise potential loss of content, set up Auto-Save Documents. (I think the peace of mind outweighs the performance cost…)
  • To keep your “desktop” clean, allow Flare to close topics you don’t need by setting Close others when opening new document. I like the option Close others with same extension and no changes, which keeps open the File List and Analyzer reports, but closes all the topics that I poked around in without working in them. You might prefer a different setting, though…

If you have other tips up your sleeve to improve Flare’s performance, please share them in the comments.

Top 5 things I like about Flare 9

MadCap Software has released a new major version of Flare, the help authoring tool I use, with much fanfare. I focus on enhancements that are most useful to me in my daily work. They are minor compared to, say, the new support of right-to-left languages, but I appreciate them because they make my work easier! For the major enhancements, visit the Flare product website.

5. WebHelp can search for partial words

The search in our standard WebHelp output can be enhanced to find partial words. (Note that performance may hurt since this option increases the size of the output, specifically of the search database.)

4. New “Condition” option in right-click menu

I can now select text or paragraphs in a topic and apply a condition by using the right-click menu. Previously, I needed to use a ribbon option (or maybe a keyboard shortcut?). While this is merely another way to add a condition, I find it convenient and supporting the way I work.

3. “Add File” dialog uses current location

Flare 9 behaves differently when I add a file, such as a topic, an image or a snippet! The “Add File” dialog now uses the current location, not some default location as before. So the new file will go “wherever I am” in the Content Explorer!

I like this for two reasons:

  • I almost never add topics to the default folder, so I had to change the file location just about every time.
  • And conversely, I won’t accidentally drop topics into the Main folder anymore where I don’t expect them…

2. Styling a table cell no longer trashes the table code

A bug would break the XML when I tried to apply a span tag to the complete content in a table cell. As a workaround, I could apply an extra unstyled space – or fix the code in the code view.

It’s a small bug fix to be sure, but it annoyed me enough that I (along with other users) submitted a bug report – and today I heard back in an email that they had actually fixed it. So this one is nice also for showing MadCap reacts to user requests!

1. Synced split-view of topic and XML code

This featured enhancement is a big help to me: I really like the “open everything” approach of Flare where I can access content and even settings files as ASCII text files and monkey around in the code, if I’m so inclined. Sometimes, I find it’s easier and faster to fix a table or a nested list in the code rather than the editor. And Flare is cool for letting me do that.

But: So far, it could be tedious to move from the regular editor to the code view and locate the place I want to fix. The new synced split-level view makes my geeky way of editing much faster as I can seamlessly move back and forth between topic view and code view!

– If you use MadCap Flare 9, what enhancements or bug fixes do you like?

Tech comm communities are people, not tools

There’s not a single social media tool or channel that’s the vital “one-size-fits-all” connection for our diverse tech comm community, but it’s their combination that lets us thrive, as I’ve learned last week.

On Thursday, a colleague and I ran into an obscure problem with review packages in our help authoring tool, MadCap Flare. We didn’t find a solution in Flare’s online help, so I reached out to a user forum.

Peer/user forums

MadCap Software Forums are provided by MadCap, but they’re run for and by the community of MadCap users. I first searched existing threads to see if someone had encountered the same problem before, without success. But I did find a thread where two days earlier two users, V. and M., had run into a similar problem that we had also encountered – and solved.

In the communal spirit of give-and-take, I outlined our solution. (The trick hinges on knowing that Flare’s review packages are really zip files which you can unpack and manipulate – if you know what you’re doing.) Then I posted our own query.

Within 24 hours, M. posted three replies:

  1. To confirm that our solution indeed works, at least in some circumstances – hence we were on to something useful that was worth sharing.
  2. To post MadCap’s reply to her support case which essentially had the same steps as our solution – hence we got our DIY solution sanctioned by MadCap.
  3. And to point out that our solution can also help us address our own problem – hence we basically couldn’t see the forest for the trees, and needed a fresh pair of eyes to consider our issue. 🙂

So it turned out that both my posts to the forum paid off. – But a small detail nagged me: M.’s greeting on the forum sounded like we knew each other, but her user name didn’t ring a bell.

Conferences

Flashback to October 2010, when I attended TCUK, the annual conference of the UK tech comm association ISTC. It was only my second tech comm conference, and the first one where I presented. My talk “Getting ahead as a lone writer” summarized my experiences and lessons learned when I had an opportunity – rather than the explicit task – to raise the quality and profile of the documentation. (You can also read about the talk in my earlier posts.)

I was really nervous the night before my talk and was very lucky to find a fellow tech writer and scheduled speaker to confide in. Karen Mardahl lent great moral and practical support. This chance encounter is another succes story: Karen has since become a good friend of mine – and most recently even a colleague!

My talk went well, and from comments I could tell that some tech comm’ers in the audience got something out of it, whether it was an ideas to try and implement or a more general sense that it might be possible and worthwhile to get ahead as a lone writer.

The feedback has been very helpful by reminding me that even minor points are helpful to some. And conversely, my biggest lesson may fall flat if no one has that same problem – or I don’t present it in a recognizable way… 🙂 Since then, I try to let conference speakers know when something struck a chord, whether it’s some practical advice or an alternative perspective on things.

Mailing lists and groups

As a member of ISTC, I get a daily digest of the association’s mailing list. I must admit I haven’t gotten a lot of use out of it so far. Maybe it’s because much content is specific to the UK, such as meetings of area groups. But Friday’s digest had an entry that merits its mention here: M. had posted, using the same user name as on the Flare forum and her full name.

Now I knew who it was: One of the attendees of my talk at TCUK 2010! We had been connected on LinkedIn for a while, so I sent her a message to thank her for her advice.

It’s the people, not the tools

I sometimes think that the tech comm blogging scene may be slowing down. At other times, I wonder if I really need yet another mailing list. But as last week’s experience has taught me, different channels have different uses to connect me to other tech comm’ers. So ultimately, it’s not about this channel or that app – it’s about connecting with people. And I, for one, am glad, proud and humbled to be part of such a vital professional scene which is stronger than any one channel.

Half-way DITA: Why some is better than none

If DITA seems like a good idea, but you cannot make the case for it, you can move towards structured writing and make your documentation “future-proof” by meeting the standard half-way.

At the company I work for, we tech writers created manuals in parallel, but separate to online help. Over time, this gave us a documentation set that was inconsistent in places and hard to maintain to boot. Topic-based authoring which reuses topics in print and online can fix that, of course.

First, a documentation standard

Deciding on the method is one thing, but we also wanted a consistent structure that made the documentation easier and clearer to use – and easier to maintain for us writers. That required a model that specifies which kinds of topics we want to offer, how these topics are structured inside and how they relate to one another.

As we looked towards a documentation standard, we had two options:

  • We could create a content inventory of our documentation, analyse and segment it to tease some structure from that.
  • Or we could rely that others had solved a similar problem before and see if we can’t use the wheel someone else had already invented.

Turns out the second option was quite feasible: The DITA 1.2 specification gives us about all the structure we need – and more. We left out the parts we didn’t need (for example, some of the more intricate metadata for printed books) and adopted a kind of DITA 1.2 “light” as our information model.

Second, the tools

Note that I haven’t mentioned any systems or tools so far! Even though it happened in parallel to the rolling out topic-based authoring as our method and DITA light as our information model, the tool selection was mainly driven by our requirements on documentation workflows, structure, deliverables, and budget.

The tool that suited us best turned out to be MadCap Flare – even though it doesn’t create or validate DITA!

Using our information model in Flare, we believe we get most of the benefits of DITA – and considerable improvement over our less-than-structured legacy content. And speaking to people at WritersUA 2011, it seems that we’re not the only one to move from less-than-structured writing to XML and something “close to DITA”.

Technically, we’ve defined the DITA elements we need as divs in the Flare stylesheets, but otherwise use the straight Flare authoring-to-publishing workflow. Flare is agnostic to whether a topic complies with DITA, is somehow structured but not complying or totally unstructured.

The benefits of DITA, half-way

To us tech writers, the largest benefit of DITA, half-way, is that we can actually do it. We could not have gotten away with DITA, the full monty, which would have required a much longer project, a much bigger migration effort and hence, uncertain ROI.

For new topics, we are committed to writing them structured, so they follow the information model. To migrate legacy topics, we’ll have to ensure they have an identifiable topic type and a suitable heading, but we can cleaning up their insides in a “soft fade”, moving them towards structure one by one. This gives us a quicker win than cleaning up literally thousands of topics before having anything to show in the new method, model or system.

So we will have been working in Flare and with our home-grown information model for a long while, before all topics actually comply with the model. But then we will have a documentation set which we can feasibly move into real structure, whether we opt for DITA or some other XML-based CMS, with or without a CMS.

This post is an elaboration of a comment thread on the “Why DITA?” guest post on Keith Soltys’ Core Dump 2.0 blog.

Beef up tech comm skills with free webinars

If one of your new year’s resolutions has been to improve your tech comm skills, here’s your chance. Industry experts offer several webinars in upcoming weeks to start you off. Many of them are free, so you really have no excuse! 🙂

Scriptorium

Scriptorium’s free webinars cover industry trends and technologies, such as:

  • Content strategy in technical communication
  • Trends in technical communication, 2012
  • HTML5 and its impact on technical communication

I’ve attended many Scriptorium webinars and have learned a lot from them. They are substantial and presented well. If you’ve missed one, you can catch up on the canned recordings.

Oh, and Sarah O’Keefe, who does most of them, has just taken #2 on MindTouch’s list of the Most Influential in #Techcomm and #ContentStrategy.

Comtech Services

JoAnn Hackos’ free webinars (announced on the DITA Writer blog) are dedicated to moving towards DITA in a 3-part series of “Crossing the Chasm with DITA”.

Hyper/Word

Neil Perlin’s free webinars are usually more tool-oriented, so they’re hands-on training sessions on topics such as:

  • MadCap Flare Mediums
  • Using Help Authoring Tools as CMSs
  • GUI Mobile App Authoring Tools
  • Creating Mobile Apps with Viziapps
  • Mobile documentation in Flare and RoboHelp

STC

STC’s webinars bring together the widest roster of industry experts, but they’re not free. They offer up to 3 webinars per week. Here are just the next six through the end of January:

  • Mental Model Diagrams: Supportive Content for Specific Folks
  • The Art of the Demo
  • Getting Yourself Into Print
  • Introduction to the Mobile Ecology
  • Designing Quick Reference Guides
  • Successful Strategies for Continuous Improvement

If you’re an STC member, sign up until January 31 and get $20 off on each webinar.

MadCap

MadCap’s free webinars are strong on tools and processes. Currently they only have one on offer about migration to Flare. But you can always check out the recordings for free. The tool-agnostic ones are quite valuable, even if you don’t use MadCap’s products.

Adobe

Adobe’s free webinars also mix tool-specific training with general topics. You do need an “Adobe Account” to register. Coming in January are:

  • Key Trends in Software User Assistance: An Expert’s Perspective – Part 1
  • Top 10 key trends shaping the Technical Communication industry of tomorrow: An industry research
  • Why upgrade from older versions of RoboHelp (X5, 6, 7 or 8) to RoboHelp 9? What is the value proposition for your business?
  • How to optimally leverage a Content Management System as a Technical Communicator
  • What is the future of indexing for technical documentation?

If you know of additional tech comm webinars, feel free to leave a comment.

Cheat sheets for Flare keyboard shortcuts

Harness MadCap Flare’s mighty, but daunting user interface with one of three cheat sheets of keyboard shortcuts for MadCap Flare.

We are starting to use Flare to get serious about single-sourcing and re-using our topics. I’ve been using Flare before, but I still don’t always know where to find a certain function or how to quickly open one of its many window panes. This is where keyboard shortcuts come in handy. Of course, I’m not the first user to find them helpful, so you can choose from three different cheat sheets:

The official full monty

The official shortcut reference in PDF by MadCap contains two lists of shortcuts, one sorted by tasks, the other sorted by shortcuts. The annotated tables fill a total of 14 pages. That’s good for an exhaustive reference, but less useful for a cheat sheet to keep next to the keyboard.

The quickie

This 1-page quick reference in PDF is by Scott DeLoach, a MadCap Certified Instructor for Flare who has written the MadCap Flare Certified Test Review + Developer’s Guide, MadCap Software’s Flare Training Guide, and other Flare Guides.

The new homegrown

This is my own new 2-page quick reference in PDF, mashed up from the two previous sources:

Click to download the 2-page cheat sheet in PDF.

It’s 1 page with all shortcuts listed by Flare element and 1 page with all shortcuts listed by action. If you’re using Flare, I hope you find it helpful.