Recommended video: What’s new in MadCap Flare 7

Here’s a timed summary of the “MadCap Flare V7 – What’s New Demo” and more resources that review the latest Flare release.

The 55-minute video is by Mike Hamilton, VP Product Management of MadCap Software, recorded on March 3. The audio is not spectacular, but other than that it’s a lively, engaging demo. You’ll find the video on MadCap’s webinar web page.

I’ve prepared this transcript summary, because I wanted to refer to individual “chapters” of the demo. I like Flare and MadCap Software, but am not affiliated with them, other than as a fan and past and future user.

More MadCap resources

Flare 7 covered elsewhere

MadCap Flare V7 – What’s New Demo, Topics & Times

0:00 Webinar preliminaries

1:30 Find more info about Flare 7 at the MadCap web site

3:40 Agenda

  • General
  • Editor
  • Workflow/Team Environments
  • Viewing/Testing
  • MS HTML Help Enhancements

5:20 1. General Topics

  • Accessibility Enhancements
  • Reports Engine (which is new, not MadCap Analyzer)

6:50 General > Accessibility Enhancements

  • Web help and PDF enhanced for users with disabilities
  • Add screen tips to graphics for screen readers
  • Optional build warnings remind you of accessibility issues: missing alternate text, etc.

10:50 General >Reports Engine

  • Create custom reports about all files in project
  • Build a report from scratch or use included report templates
  • Examples: Show all conditions in report files, show all topics with changes and comments

14:30 2. Editor Enhancements

  • QR Codes
  • Equation Editor
  • Vector Graphics
  • Auto Suggestion
  • Alias Editor Enhancements
  • Table Enhancements
  • Customize Flare UI Grids
  • Remove Inline Formatting
  • Shortcut Buttons (Snippets/Variables)
  • Paste Options

15:20 Editor > QR Codes

  • QR codes are smartphone-readable (“square barcodes”)
  • Include an URL, e-mail address, or text in print output
  • For online output, you can make the barcode clickable…

18:05 Editor > Equation Editor

  • Supports MathML code
  • Formulas are inserted in author mode as stylable, scalable vectors
  • Formulas render as lossless, non-blurry postscript in print & PDF
  • Formulas render as graphics online

20:45 Editor > Vector Graphics

  • Supports inserting SVG, PS and EPS graphics in topics
  • They allow lossless scaling
  • Render as lossless, non-blurry postscript in print & PDF
  • Render as graphics online

24:10 Editor > Auto Suggestion

  • Can be turned on and off
  • Reminds you of existing snippets (=sub-topics) and variables (=module names)!
  • Makes reuse of snippets and variables easy
  • Supports added common phrases, too

26:25 Editor > Alias Editor Enhancements

  • Completely reorganized
  • Shows complete, incomplete and missing aliases
  • You can auto-generate file IDs from pattern

(29:20 You can move tabs of open pages around.)

30:30 Editor > Table Enhancements

  • In Flare editor, you can convert text to table and table to text
  • (Be patient with Mike; he needs a minute to find the feature in the GUI…)
  • You can also merge tables

34:15 Editor > Customize Flare UI Grids

  • You can customize any dialog, any GUI grid in the Flare editor for custom column layout and appearance

35:50 Editor > Remove Inline Formatting

  • You can remove inline formatting easier, without highlighting exactly

37:45 Editor > Shortcut Buttons (Snippets/Variables)

  • Icons in text workspace provide faster access to selection of snippets and variables

38:50 Editor > Paste Options

  • Paste text as paragraph, list, table

40:00 3. Workflow/Team Environment Enhancements

  • SharePoint Integration
  • Subversion Integration
  • External Resources
  • Review/Track Changes

40:15 Workflow/Team Environments > SharePoint Integration

  • You can integrate Flare projects into SharePoint or import any SharePoint file into Flare

41:15 Workflow/Team Environments > Subversion Integration

  • Subversion is now directly integrated
  • Without 3rd party plug-ins, such as Tortoise
  • This is now like Microsoft Team Foundation Server and Visual Source Safe

42:15 Workflow/Team Environments > External Resources

  • You can use any external resource/file in Flare
  • … even if it’s not part of any Flare project
  • Link to any network file that’s accessible
  • However, these resources are then outside of Flare’s source control

44:30 Workflow/Team Environments > Review/Track Changes

  • Comments and Track Changes essentially acts as in Word
  • With multi-colors, strike-through
  • Several users can see each other’s edits
  • You can accept/reject changes individually or accept/reject all
  • This works only in the Flare editor and in Contributor (previously X-Edit)
  • It doesn’t work in any output

49:10 4. Viewing/Testing Enhancements

  • Chrome
  • Preview Any Format
  • WebHelp Output – Choose Browser

49:10 Viewing/Testing > Chrome

  • Fixes bug that you couldn’t view (any vendor’s!) local web help in Chrome browser

50:20 Viewing/Testing > Preview Any Format

  • You can quickly select to preview the topic in any defined target format, not just one selected format
  • Easier, more realistic previews

52:30 Viewing/Testing > WebHelp Output – Choose Browser

  • You can quickly check web help output in any installed browser: IE, Firefox, Chrome, Safari

54:10 5. MS HTML Help Enhancements

  • You can import a .CHM file as a Flare project, including the TOC and index

55:30 End

Top 5 reasons to attend a tech comm conference

The benefits of attending a tech writing conference go way beyond learning about methods and tools. That’s why I really look forward to Writers UA next week!

Most reasons are kinda obvious really. But put them all together, and they create a serious pre-conference buzz, almost like when you follow a band on tour or attend an intense music or theatre workshop. If you’ve never been to a conference, I can assure you all the benefits will make it worth your while. And if you know what it’s like, I invite you to add your own reasons in the comments.

(tekom 2010, photo by jophan).

1. Learn about methods and trends

This is the “official”, token reason: Of course, you’ll learn about tech writing methods, tech comm trends and case studies. Look at the conference web site which gives you an idea what to expect. (Here’s my earlier list of links to conferences this year.)

2. Check out new tools and versions

Many conferences double as a trade fair, so you can get a guided tour and a hands-on impression of new tools without installing trial versions and wondering “now what?”.

3. Meet experts (a/k/a make friends)

I’m always amazed at the combined expertise at conferences. And I don’t just mean the speakers. Go down to the hotel registration desk, and you may meet someone whose tweets you’re following. Sit down at the bar, and you may chat with someone who’s been using the content strategy you’re pondering. The chance acquaintance at the dinner table may have been using the tool you’re considering.

4. Connect with the hive mind

Often you can come with a specific question in mind and find ways to answer it. TCUK10 had a rant session that also gave people the opportunity to solicit answers from attendees. WritersUA has a more formalized Q&A opening session: “Let’s Look in the Mirror and See What We See“. Where else can you get instant, free consultation from dozens of experiences tech writers at once?

5. Visit with friends

If it’s your first conference, you’ll enjoy to get to know people better who you’ve just met. Then you can look forward to meeting people again you haven’t seen in a while, but you’ve seen their tweets, blog posts or articles.

Bottom line: Soak up inspiration and motivation

It all boils down to this: A conference can give you inspiration, motivation and confidence that you’re not alone, that you’re doing something professional and totally worthwhile! If that isn’t worth your time (and maybe even some of your money…) 🙂

Practical tip: Share costs and benefits

It’s pretty obvious that your company shares in most of the benefits. So it’s in their interest as well that you attend a conference. If your boss has more understanding than budget, consider if you could split the cost:

  • Maybe you can pay (and write off) travel costs?
  • Maybe you don’t have to take days off to attend?

[Update 8 March: Bill Albing answers that once-a-year conferences are sooo yesterday in the age of social media. Make sure you also read his Top 5 Reasons to Avoid a Tech Comm Conference.]

Your turn

Do these benefits work for you? What other benefits can you think of? If you’re freelancing, can you land new contracts at a conference? Please leave a comment.

Organize bookmarks in folders by task

Make the most of bookmarks by sorting them by tasks.

That’s the lesson I learned after months of trudging along with a looong list of bookmarks. I would add links for later reading, then randomly pick pages to read or otherwise process, and it was not working.

Around New Year’s, I cleaned up the mess, threw out dead links and pages that seemed merely vaguely interesting. The remainder went into separate folders. This has been working really well for me so far: I remember and find bookmarks faster, and I process them faster (which means reading and filing or deleting).

Organize by task, not by content

The trick for me was to create bookmark folders by tasks, not by subject matter or contents! I now have the following bookmark folders:

  • Tech Writing with pages to read and archive useful ones.
  • Blog with pages to write about in this blog.
  • [Project] with pages to work on for articles or presentations, one per project.
  • Portable Freeware with pages of software to try out.
  • Travel with pages of hotels and restaurants to visit.
  • Inspire with pages to get me unstuck from writer’s block.
  • Lookup with pages to look up grammar rules, translations, prices, streets, etc.

Why does this work?

It works for two reasons:

  1. It’s basically following our own professional advice: Create documentation task-based, not based on the stuff you organize, whether it’s a user interface or random web pages.
  2. It’s inspired by GTD (Getting Things Done): Get productive by ensuring you can simply crank widgets as a tech writer.

Bonus tip

Sync your bookmarks across all your machines for even better order and productivity. I use xmarks for Firefox to ensure all my bookmarks are always up to date, regardless of which PC I use. When I’m on someone else’s machine, I can still look up my bookmarks online.

Your turn

How do you organize your tech comm bookmarks? Do folders work? Is there a better way? Please leave a comment.

Recommended read: Practice technical writing

Becoming a better tech writer requires practice.

Mike Pope, tech editor at Microsoft in Seattle, has a brilliant blog post about 12 ways to practice tech writing. The catch is he means “practice” like a musician, so you learn to do stuff better than yesterday – instead of just doing the same things over and over.

Over the last years, I’ve tried all 12 ways, and they’ve all helped me to become a better writer. And most of them can be fun, too, at least most of the time… 🙂

Here are just six of the ways as a teaser, but I highly recommend you head on over to Mike’s post to find out about all of them with details and examples.

1. Read other technical writing attentively.
2. Read about writing.
5. Writing something outside your usual material.
7. Edit someone else’s work.
10. Learn new tools and new ways to use your existing tools.
11. Talk to other writers.

Choosing the Right Tools

Choosing the right tools is obviously important – but also hard, when recommendations emphasize unique selling points that make comparisons difficult.

My fellow German Marc Achtelig has put together three pages with criteria to help you choose the tool that does what you need:

The pages are very thorough and well thought out, but they don’t connect directly to products. As such, they’re great to help you make up your mind before you consult the pages of useful tools on his indoition web site. Or you can consult the HAT matrix and plug in all the features you’ve decided you need.

Marc also has a documentation quality check list which covers similar grounds (though shorter than a book can) as Gretchen Hargis, et al. in their book Developing Quality Technical Information.

As a bonus, all the information Marc has collected can be downloaded as a 100-page PDF.

Master change – with skills or attitude?

In the face of fundamental changes, skills seem to follow attitude. That’s my second conclusion from Sarah O’Keefe’s webinar about “Managing in an XML environment”. Read on for my summary of her argument and my comments. (Or see my previous post “Top strategies to embrace cost metrics” for more insights.)

Technical writers need a different skill set when moving to structured writing, topic-based authoring or an XML environment, Sarah explained. The general types of skills are the same as when writing “old style” books, such as user manuals: You still need writing skills, people skills, tool knowledge and domain knowledge. But the skills shift focus and application.

Shifting skills

Basically, Sarah argued, you need less tool knowledge and more of the other three skills – and better:

  • Writing skills focus on writing topics and their reuse. Writing topics requires more structure and better compliance to templates than book-like documentation which suffers free-form writing more easily. And topic reuse involves a lot of collaboration.
  • People skills enable increased collaboration. Colleagues may reuse, tweak and add to your topics. In fact, there’s no such thing as “your” topics, once they are subsumed into a larger collection of topics to which several colleagues contribute.
  • Tool knowledge decreases due to the separation of writing and publishing. Yes, you need to learn new tools, Sarah allowed, but that’s an initial effort. Much of the tool effort is split off into implementation and production of the documentation.
  • Domain knowledge steps in to sustain documentation quality. You can no longer hide behind the tools and improve specific parts of the documentation by layout or presentation.

Among all these changes, Sarah said, the biggest challenge is actually to come to constructive collaboration among writers. In a structured environment, the emphasis is on the process of writing and maintaining topics, not on the deliverable end product, such as a manual. Writers share responsibility for topics – which is very different from “owning a book”.

That’s why Sarah urged us not to “succumb to BOSSY, the Book Ownership System SYndrome” and to remember that “CROC is your friend” which stands for “Creating Reusable Objects and Collaborating” (somehow “CROAC” seemed a less appropriate acronym, I guess…).

Shifting attitudes

I agree with Sarah’s premise that topic-based writing requires different skills, with her analyses and her final recommendations. Yet I think the difference she describes is one of attitude rather than of skills:

  • Writing skills are different, not harder. I think it’s just as difficult to write a good, “old style” user manual as writing good topics. Writing topics seems to require more skills, because it’s new and different. I don’t think it’s actually harder, once we writers come to terms with its newness – and our resistance against it, however good reasons we may have.
  • People skills are overdue. I guess we tech writers feel the same pressure as many other professions: To collaborate, to heed stakeholders, to reach out to other teams and to connect to customers. If we notice the pressure more, it may be because we’ve worked in relative isolation. Mastering any change is much easier with a bunch of like-minded people than when you feel alone, stuck in the trenches.
  • Tool knowledge is overrated. Banking on tool knowledge isn’t the best career choice since your job hinges on a tool – and a specific version… When your tasks change, there’s the chance that your tool isn’t the best (anymore) for what you need to do. Tech writers should be really good at wrangling content (props to Scott Abel), not tools. If you distinguish methods and tools, I think you’ll find that it’s much faster to learn a new tool than to learn a new method, such as topic-based authoring.
  • Domain knowledge is second to content proficiency. While one can never have too much domain knowledge for a job, our key skill is to structure and relate that knowledge. I firmly believe that you should “always hire the better writer“, for two reasons:
    1. It helps your corporation to build up complementary skills: Your corporation probably has lots of domain specialists already – but how many really good writers does it have?
    2. In my experience it takes a year or two to become a decent domain specialist – but it takes longer than that to become a decent writer. (Though your mileage may vary…)

That’s why I come to a different conclusion. How successful we tech writers are when changing to a environment or processes depends less on our skills, but more on our attitude to them. There are at least two different ways we tech writers can regard our deliverables, our writing skills and our tool knowledge:

  • If they are our assets and define what we do, any change in environment and processes will threaten us.
  • If they are the results of previous learning, we can embrace change with the confidence that we can rise to the challenge again.

For example, when I feel I own a manual, any review, any editing has serious crisis potential already. I know what it’s like, I’ve been there… But once I feel shared reponsibility for the documentation at large, it takes on a more constructive, larger dimension, where we’re all in it together. Well, most of us, anyway… 🙂

Your turn

What determines how you face change: Your skills or your attitude? Can training and skills ensure buy-in for a new environment or processes? Or is it more important to have a self-confident, competent attitude?

Help smash tech writing dogmas!

I confess: I have a couple of dogmas about tech writing – though I generally consider them detrimental to communicative, collaborative jobs such as ours.

By dogma, I mean here a firmly held belief that I assume applies universally, if only because I haven’t been convinced otherwise yet… 🙂

However, seeing how much I’ve learned from your great comments and opinions to my previous posts, I’d like to invite you to chip away at my preconceived notions. Maybe my dogmas are unfounded and silly…

So here goes, meet two firmly held beliefs that I’ve acquired over the years:

Don’t build your own HAT!

I don’t care how cool you are as a software company, I firmly believe that you should not build your own help-authoring tool (HAT), unless that is actually (part of) your business.

True or false? I believe it’s true: The initial project to build the thing is like reinventing the wheel, but you may actually get all the cool features you think you need and don’t get from a third-party system.

But I’ve yet to see a company that can sustain the required maintenance efforts: Development for profit goes before development for internal cost centers, and just about anything goes before documentation. So dev resources for the HAT are always scarce and low-priority. As a result, bug fixes, updates and enhancements to the HAT take longer than they should. Meanwhile, writers work inefficiently and with frustration which often brings down the quality of the help.

I also doubt it makes economical sense to continuously invest non-billable development time when you can get a third-party product and maintenance plan, usually for a fraction of the cost.

Don’t buy a tool to fix your processes!

Blame your tools all you want for why your documentation is bad and/or painful to create, I firmly believe that getting a new tool won’t fix that.

True or false? I think it’s true: Frequently, bad tools beget bad processes, but you need to fix your processes separately. Problems with the tool can be so obvious, they tend to obscure ill-designed processes.

Actually,  I recommend to fix the processes first, so you can then buy the right tool that supports them. A good tool makes it easier and more efficient to create good results, but good pots and pans don’t make you a master chef.

Have at it!

Please help out a fellow tech writer: Leave a comment and give some reasons, if you think:

  • Dogmas deserve to die, and these especially!
  • Dogmas are generally bad, but these are actually true!
  • Dogmas rule, and we need more of them!

Portable apps for tech writers IV: Wrangling files and PDFs

By now you maybe know that I’m fond of portable apps. That I use them to write, take screenshots and look up stuff in dictionaries with them. But wait: There’s more! No matter how well I manage my contents and architect my information, sometimes files just go unwieldy on me. That’s when they come in:

My favorite apps to wrangle files

Now where’s that file again? Baregrep finds files by name, very quickly – much faster than Windows’ file explorer! And it finds text within ASCII files, again very quickly. It’s my favorite tool to find elusive entries in .txt files or help contents in .html or .xml files. Unix users will recognize the name: This is really a “bare” grep that also masters regular expressions. You’ll have to live with a nag screen upon startup, but, hey: It’s free…

Uh, how come there’s so many of them? Easy Duplicate File Finder finds, uhm: duplicate files. It compares not just file name and size, but contents, too! So when your “to read” folder has gotten too big again, it’ll point out that white paper which you’ve downloaded twice – with different names… It’s also great to clear out project directories where you may have created countless copies of files.

… and now without the spaces. Bulk Rename Utility comes recommended by reader JosephK. He writes: “Bulkrenaming of files with regexp expressions can be done with BulkRename. The interface takes some getting used to.”

For intrepid explorers. XYplorerFree is my portable file explorer of choice – and it’s not even double-pane. But I like it for its comprehensive file-finding and various display options, so I don’t mind that the last free version is almost 4 years old. If you want dual-pane explorers, try freeCommander and UltraExplorer, both of which rank highly. Or try some of the other file explorers in The Portable Freeware Collection.

Portable zipping. PeaZip is my archiving/compression tool of choice. It claims to handle 118 file types. At least, I’ve never had an archive type it couldn’t open. Be sure to grab the “PeaZip portable_standalone” package.

In sync. DSynchronize is a reliable file synchronizer with a straight-forward interface. You can preview what files will be added, deleted or overwritten before committing the changes. You can also opt to sync only newer files or to sync both sides. If you don’t like this one, try Toucan which is a bit fancier and also available from portableapps.com. (Remember that portableapps.com versions don’t require the portableapps.com platform – you can just point their installers anywhere…)

…got til it’s gone. CyberShredder removes files. For good. It overwrites them, up to 7 times. This can be useful when you want to be sure your files are not on the machine after you leave.

Going truly portable with PDFs

It’s a bit ironic that it’s called “Portable Document Format”, when it’s so difficult to modify PDFs – if it wasn’t for portable PDF editor PDFTK Builder. It lets you reorder, delete and duplicate pages in a PDF file and merge pages from multiple PDFs. You can also split a PDF into files with one page each. (Splitting and merging a subset, however, often gives you much larger file than the source, so it’s more like a first-aid kit for emergency surgery.) You can also rotate and stamp pages and protect your documents with passwords to read or change the documents.

If you just want to read PDFs on a fast, portable reader, I recommend Foxit Reader. Others prefer the even smaller Sumatra.

What tools do you use to wrangle files on the go? Feel free to leave a comment.

Portable apps for tech writers III: Dictionaries

I don’t just write and take screenshots with portable apps, I even use them to look up words, despite Wikipedia and countless online dictionaries. I like the seamless lookup from other applications with a click and don’t want to rely on being online. Fortunately, there are some very useful and usable apps out there. Here are my favorite portable dictionary apps.

“Lookup Central”, all in one

WordWeb combines a portable offline dictionary and thesaurus with tabbed browsing to look up words in popular web sites. Entries are displayed in two frames, with definitions and examples in one and the thesaurus in the other. (To see the full screenshot, just click it.) The free version of 30 MB comes with Princeton University’s WordNet wordbase of about 150,000 entries – and an unusual license agreement: “WordWeb free version may be used indefinitely only by people who take at most two commercial flights (not more than one return flight) in any 12 month period…” The paid “pro” version gives you more definitions and pronunciations, you can add online sites and buy extra dictionaries, thesauri and word lists. Click the screenshots to see a comparison of WordWeb and TheSage:

The “language reference system”

TheSage combines a portable offline dictionary and thesaurus with tabbed browsing… – Yes, just like WordWeb does. As far as I can tell, it even uses essentially the same wordbase. The main difference is the layout: You can expand and collapse the results by definitions, examples and thesaurus entries. You can also customize the online lookup sites. With 210,000 definitions taking about 20 MB, it has an edge over the free WordWeb version – if you can get used to the interface.

For a second opinion, the Freewaregenius has an older review of TheSage with a comparison to WordWeb in passing.

The multilingual dictionary

LingoPad translates words between German and English or other languages. I must admit this one doesn’t get much use when I’m online because WordWeb links straight to LEO. But it’s a reliable tool, especially when you’re mainly working in translations from or to German.

The classic dictionary bookshelf

Lingoes is a dictionary platform that lets you add all kinds of dictionaries. Of all the apps, it’s most similar to the long defunct Microsoft Bookshelf – which was, of course, neither free nor portable, but a cool solution in its time. Lingoes is a bit out of scope, though: Its license agreement limits use to “non-commercial purposes in non-business, non-commercial environments”, and it seems unclear whether the dictionaries download packages are properly licensed.

Which dictionaries do you use? Do you prefer online or offline?

Portable apps for tech writers II: Screenshots

Suppose you’re wise to portable apps and how to tweak text with them, with or without the apps mentioned in my previous post Portable apps for tech writers. But how about screenshots? Anything portable there? – Oh, good! I thought you’d never ask… 🙂

My top 3 portable screenshot apps

Top prize: PicPick Tools is my #1 screenshot app. It’s got everything I need: Quick and easy screenshots of desktop, window or screen area, quick change of output setting, auto-save to my project directory, a screen ruler and magnifier and a simple image editor. Most of the time, I take straight screenshots without call-outs, so I want an app that lets me do that quickly and keeps out of my way. PicPick does this best of all the screenshot apps I tried; it runs in my task bar. The problem with this is that, according to the product web site, the “portable version of PicPick [is] only for private, personal and not commercial use”.

Runner-up: FSCapture is very similar to PicPick. The problem with this is that it’s no longer a free app. The link takes you to the last free version 5.3 of February 2007 which works fine. However, it excludes some of the features baked into the latest version 6.5 and PicPick Tools, such as the screen ruler and sending captured images directly to Word, PowerPoint and an FTP server.

Honorable mention: The unpronouncable PrtScr affords the stylish whimsy of an animated preview. You need to see it to believe it – check out the video below. It’s great for quick and dirty screenshots with markups, but its emphasis on free-hand drawing and cropping makes it less suitable for pedantic operations. The problem with this (and you knew there had to be one) is that you pretty much have to create your own portable version by installing it, copying the program files to your portable directory or stick and uninstalling it.

[Update: I just remembered that freewaregenius has written up PicPick and PrtScr so you can get exhaustive second opinions on them.]

What do you think, is it worth to pay for screenshot toolsfor the extra features when freeware basically gets the job done?

Here’s PrtScr’s cool demo rock video: