Second day at MadWorld 2014

A well-rounded program and excellent organisation at the second MadWorld user conference avoided many of the traps that can mar a sophomore effort and point to a way of growth into the future. The second day again saw great informative sessions and networking around doc issues and careers, not to mention lunch and drinks under the San Diego spring sun… :-)

At MadWorld 2014 welcome event

Advanced single sourcing of content in Flare uses a clever combination of snippets and conditions which are called, not surprisingly, “snippet conditions”. These allow you to maintain reusable chunks of content with slight variations – which one is ultimately displayed is controlled on the topic that contains the snippet.

In his single sourcing presentation, Paul Pehrson had many more tricks up his sleeve:

  • To repeat a topic in the same TOC (with or without variation), put the topic content into a snippet and embed it into an empty unique topic container – else your breadcrumb trail in online help goes haywire, because it cannot know which of the two occurrences it should refer to.
  • To reuse similar front matter across several PDFs, you can put the front cover, the copyright page, and the table of contents into a TOC of their own, import it as a nested TOC into each target and control the individual differences with variables.
  • To maintain individual project styles and corporate styles, create your project CSS and import the corporate CSS into it by using the @import CSS command.
  • To share condition sets or variable sets across two projects, store them as External Resources where you can keep them in sync with one another.

The lightning talk round was a very colorful fast-paced session. Passionate speakers addressed widely different topics, including

  • A MadCap version of Jeopardy by Pam Coca (“Who is our tech comm game show host?” :-) )
  • Several ways to avoid inline formatting with the help of Chuck Norris by Scott DeLoach
  • MadCap’s latest group of spokespersons: Dentists who recommend Flare for more smiles than any other help authoring tool by yours truly

The 6 topics wouldn’t necessarily have warranted a full session each, but they were fun and valuable to have in a compressed 5-minute format.

Our addiction to meaning gave attendees food for thought as I led them through a quick overview of semiotics and mental models which included Japanese restaurants and misheard song lyrics. In the Q&A session we explored how we could apply such insights into cognition to offer users confidence in their tasks along with meaningful instructions.

Writing, editing and translating topics is frequently done by people who don’t have Flare and don’t need it either.

Mike Hamilton at MadWorld 2014

Mike Hamilton showed several scenarios to address special demands in authoring workflows:

  • For writing and editing users of Contributor, you can customize exactly which Flare files, such as snippets, condition and variable sets, are available to them. You can also lock down certain text in Contributor templates to enforce structure and labels.
  • For reviewers using Contributor, you can now apply conditions and variables when creating the review package, for example, to keep internal data out of packages for external reviewers.
  • For translators of Flare topics, you can create customized export packages and choose to preserve the code of snippets and variables or to convert them into flat text.

For MadWorld 2015, my guess is that we might see fewer sessions on basic Flare techniques which are well-covered in available webinars and other information online. Instead, I’d recommend more sessions that show how MadCap supports tech comm workflows and business cases. These could cover, for example:

  • How to integrate documentation and training content with Flare and Mimic
  • How to build a business case around single-sourcing topics that can turn tech pubs into a profit center which leverages content as corporate assets
  • How to use MadCap’s products in corporate, large-scale products, like Lynn Carrier has shown this year.

Overall, MadWorld was a very instructive, very fun event! The user conference format affords a welcome focus which sometimes gets lost in industry-wide conferences which have to try to satisfy more disparate needs.

CEO Anthony Olivier spoke of welcoming us all to the “MadCap family”. I think that metaphor is stretching it a bit. For me, it feels more like a versatile community of dedicated, often enthusiastic users who get to hang out with one another and with, say, a band we like – and we get to spend some time back stage in the hospitality suite. :-)

First day at MadWorld 2014

The applicable advice about MadCap products from speakers and staff, the profound discussions about tech comm in general, and attendees’ enthusiasm to share and learn from another make MadWorld 2014 a perfect combination of a tool-centric user workshop and a “regular” tech comm conference.

The hip Hard Rock Hotel adds a flair of giddy excitement – after all, some of us 200 tech writers are a little too nerdy to feel comfortable when they’re treated like rock stars… :-)

The welcome event started with a tongue-in-cheek video: MadCap’s signature cartoon figure Simon has become addicted to – the horror! – inline formatting. His brave MadCap colleagues stage an intervention to save him… I hope this video will soon come to a Youtube channel near you because it’s a lot of fun to watch!

At MadWorld 2014 welcome event

Product Evangelist Jennifer White introduced many of the MadCap key players in attendance, then MadCap CEO Anthony Olivier welcomed us and encouraged us to join the “MadCap family” to learn and network.

To turbocharge our authoring, Nita Beck showed us how we could bypass some of the pretty, but slow-to-use Flare ribbon features for faster alternatives:

Nita Beck's session at MadWorld 2014

  • Custom templates for topics and snippets can include  much of the recommended structure and formatting. Filling in such a template saves the time to manually reconstruct such structure and formatting in just about every template.
  • Contributor can be used by tech communicators as a low-distraction alternative to Flare for initial drafts which keeps many of the more complicated features of Flare out of the way for the time being.
  • Keyboard shortcuts for many Flare features are faster than doing the same with the mouse.

Pattern recognition elicited a lively Q&A session from the capacity crowd in my presentation. We found that, whatever patterns we recognize, they generally depend on their context in which the retain meaning. From there, we branched out to discuss information architecture and user experience design and how they also rely on patterns.  We also tried to tease out the pattern why my slides had broken the nice arrows and replaced them by the average sign in all places – but one!

Flare projects can support a scalable content architecture, as  Lynn Carrier showed. She described her employer’s project of introducing single-sourcing with Flare to cope with 3000 pages of docs per writer per year. The keys to her successful project were:

  • Ownership to involve all writers and tap into each writer’s skills and interests to assure them they weren’t writing themselves out of a job.
  • Infrastructure to make sure they have the tools and processes in place to create the deliverables in the structure and quality they customers need.
  • Reuse to ensure the most efficient way to single-source content, they carefully mapped out where and when to use snippets, conditions and variables. Conditions are heavily applied on folders and topics move around in the folder structure so they are available for the products and versions where they are needed – and only there.  They use few variables because in-sentence, they create problems during translation.
  • Publishing based on TOC templates and target templates ensures consistency in structure and easy maintenance.

Since we have very large projects as well, this was a very valuable session which gave us lots of ideas how to use Flare’s reuse and template features in a corporate environment. Lynn will have another presentation on the second day to show how a wizard enables customers to compile exactly the documentation they need into a PDF. This is something we’ve long thought of doing, so seeing her solution will be a great inspiration for us!

Face-to-face support beats written documentation any time which is why the “hospitality suite” is so great. It’s like walking into MadCap’s helpdesk as if the smartest MadCap users were your colleagues in the next room.

A good balance between sessions and networking opportunities allowed us to trade quirky, but powerful solutions around Flare that users have come up with, to trade career stories and make new friends among a group of technical communicators as diverse and friendly as you could hope to find at any tech comm conference.

Chilling in the early evening at MadWorld 2014

Well done, MadCap, I’m psyched for day two!

Rate and improve tech comm with the Net Promoter Score

You can use the Net Promoter Score to rate and improve technical communication – but it works best on the scale of corporate content for which the score was designed. Here’s why and how.

The Net Promoter Score (NPS)

The Net Promoter Score measures customer loyalty and satisfaction with a company or offering.  It boils down difficult issues with perceived quality to a simple question:

How likely are you to recommend our company/product/service to your friends and colleagues?

Usually, the answers are ranked on a scale from 1 (highly unlikely) to 10 (very likely). You distinguish the percentage of respondents in three groups:

1

2

3

4

5

6

7

8

9

10

Detractors

Passives

 Promoters

  • Detractors are people who replied with 6 or lower.
  • Passives are people who rated your offer as 7 or 8.
  • Promoters are people who answered 9 or 10.

The NPS is the percentage of promoters minus the percentage of detractors: If 20% of your customers are promoters who really like your offering (and answered 9 or 10) and 30% don’t think too highly of it (and answered 6 or lower), then your NPS is 20-30 = -10. Generally, an NPS  above zero, indicating more promoters than detractors, is considered a good thing…

NPS for tech comm?

So how can we apply that score to tech comm? Are customers loyal to a help system? Are they likely to recommend it to friends or colleagues? Probably not in isolation of the described product.

There don’t seem to be a lot of ideas “out there” that connect NPS to documentation, but one article by JoAnn Hackos does: Influencing the Bottom Line: Using Information Architecture to Effect Business Success.

The key to turning the NPS into a useful tool for documentation is to take the scope from the NPS, not from the documentation! Hackos shows how we can relate the NPS to corporate and product content as a whole. This includes tech comm, but also marketing and sales content. This is what drives the customer experience which the NPS reflects. And it takes improvements in the corporate-wide content and its information architecture to increase the NPS.

Hackos describes a company which found that content contributed to the low NPS:

… senior management became advocates for significantly improving content quality. That meant changing the relationship between the technical authors and the product developers, requiring that information architects establish close relationships with customer support and training, and redefining the type of content that would be delivered to customers in the future.

- Sometimes, tech comm can adopt management tools to their purpose and scope, but with the NPS it seems most feasible to plug in to the corporate use of the tool.

Does this make sense? Can tech comm benefit from NPS and improvement initiatives? Or is that a hare-brained idea, and we should really stick to key performance indicators suitable for tech comm?

Tech comm conferences too far, too costly?

European tech writers who don’t have the time or the money to attend a tech comm conference can still get a lot of knowledge and networking by attending the tekom Europe Roadshow – right in their backyard, comparatively speaking!

tekom Euurope Roadshow logo

The tekom Europe Roadshow puts on one-day events which are easier to get to from many places around Europe and waaay cheaper than full conferences. They bring together professionals from the region for presentations, discussions and networking.

Find the roadshow event nearest to you:

  • Paris, France: Monday, September 8
  • Ghent, Belgium: Wednesday, September 10
  • Eindhoven, Netherlands: Friday, September 12
  • Copenhagen, Denmark: Tuesday, September 16
  • Warsaw, Poland: Thursday, September 18
  • Istanbul, Turkey: Monday, September 22
  • Bucharest, Romania: Wednesday, September 24
  • Vienna, Austria: Friday, September 26

This year’s topic is:

TechComm Workflow & Media Production
Integrate Intelligent Media Production in Your TechComm Workflow

But even if that is not your professional focus, it might still be worth going for the contacts.

For more information, visit the event web site.

(Full disclosure: I have spoken at an early precursor of the tekom roadshow and think it’s a brilliant format, but I’m not involved with this event series.)

Why a content spec saves you time and money

A content specification will save you troubles, time, and money, especially when you’re not the lone writer on a documentation project. It will ensure that you offer your users consistent and holistic documentation across a team of writers.

A content specification is a list of all topics to be created which ideally maps planned topics to requirements and/or designs to ensure comprehensive and complete documentation. It usually comes in a table with one row per topic, listing:

  • Topic heading and/or file name
  • Topic type (concept, task, reference, or whatever else you may use)
  • Topic owner
  • Writer (in case writers may be different from topic owners)
  • Reviewers (for example, subject-matter experts)
  • Date ready for review or for post-review editing (depending on your workflow)
  • Mapped deliverables (where the topic appears, for example, a certain user manual, the online help, etc.)
  • Time estimate (how long will it take to write the topic, optionally, including review)
  • Documentation task type, to help you estimate time:
    • Create new topic
    • Major rewrite of existing topic
    • Minor fix or addition to existing topic

Without it, you risk delivering a bunch of topics with gaps in some places and overlaps in others. You can still string them together, but no overview topic can convey a coherent content experience, if you didn’t plan for it and bake it into the topics and their structure.

So a content spec is a blueprint of your documentation project, just as you would create one before you start building a house – or design any kind of experience.

Yet content specs often elicit negative reactions…

“Oh, but we’ve managed without one so far…”

Many tech writers I know are very competent, and a few are lucky to boot. Considering all their projects with more than, say, 50 topics which didn’t use a content spec, I’d bet half of them are incoherent (“organically grown” is an oft-used euphemism).

The cost doesn’t stop at poor user experience. Such examples are also more difficult and more expensive to maintain, especially if you have overlapping topics and don’t remember to update both of them…

“Bah, reality eats specs for lunch…”

To an extent, yes. But on the whole, reality is an orderly patron. In my experience, the final documentation reflect the approved content spec in up to 80% of the topics. An average 10% of the topics get added during the writing, where concepts or prerequisite and auxiliary procedures are found missing. Another 10% of the topics get reorganized because the initial content spec misunderstood something, or because content simply makes more sense somewhere else.

“Even if, we’ll fix it later…”

Yes, you can. But once again it’s very expensive. Remember that the list of topics is only one result of the content spec. Their structure is another. Finding that a structure by workflows is inferior to a structure by, say, instrument, requires not just re-ordering topics, but re-writing a lot of them.

You can avoid this by drawing up a complete content spec before you write a single topic and getting it signed off by the key stakeholders, so they know rather well what documentation they will get. The 20% deviations mentioned above are usually justifiable, if they conceivably improve the deliverables.

- Given that content specs are a big help in creating and maintaining efficient and effective user documentation, I strongly recommend using them. If you have any experience with or without content specs, I’d love to hear it.

What’s new in MadCap Flare 10, the nitty gritty

Flare 10, the annual major release of MadCap’s flagship Help Authoring Tool, includes several major enhancements that make Flare easier and faster to newcomers and editors of marketing content. And many smaller enhancements target the hardcore techcomm heavy users. The well-balanced improvements testify that MadCap listens to many of its users.

Today, I’ll focus on the enhancements that I enjoy most – many of them are smaller improvements for heavy-duty tech comm users with large projects and many topics. (An earlier post covered the more obvious strategic enhancements.)

  • Improved build times are probably the most crucial enhancement for us. We have some crazy large projects, and we’re happy to see that build times for web help and PDF alike decreased on average by 10 to 30%. Apparently, Flare 10′s re-engineered build process causes more read/write operations. That means a fast hard-disk drive with, say, 7200 RPM or a solid state disk help you to really benefit from the improvements. (If you don’t know your RPM speed, find your HDD model ID in Windows’ Device Manager, search the web for that ID and you’ll find the RPM speed as well.)
  • Robustness is improved with a Crash Reporting System. Given our large projects, Flare could be really slow at times and occasionally crash. I don’t recall ever losing any data, but it was still unnerving to see Flare disappear suddenly. I like that Flare 10 has better exception handling and captures a lot of run-time errors with an error dialogue.
  • Customised project export allows you to tailor the content you share with other writers, translators or MadCap support. You can export projects not just as a whole, but also by selecting a target, a set of conditions or even file tag settings. For example, you can select a target and export that (along with the target’s conditions applied) to your translator. I use file tags to track topic status and translation language – and I like that I can export complete, stand-alone projects which contain only the relevant topics.
  • Customised review packages benefit from the same restrictions, and we can select a target or apply conditions to collect only relevant topics. Oh, and topics in a review package now automatically bring along the snippets the link to which is a nice, intuitive touch.
  • A Find and Replace widget in the XML Editor lets me find expressions in the active topic much faster.

Find and Replace widget in Flare's XML Editor

  • Drag-and-drop for conditions and variables makes it easier to select these elements which are now listed individually in the Project Organizer window and drop them into topics where I need them.
  • Apply conditions in the XML Editor. I have several “dimensions” of conditions, such as print vs. online and version A vs. B. And sometimes, I lose track whether I have all scenarios covered. This new feature makes it easier and faster to see when I have content missing for “print + version B”, for example.

Button applies conditions in XML Editor

  • File navigation improvements benefits especially users who have a lot of topics and a lot of topic reuse.
  • Find and Replace in Files has been revamped to offer more options for tailored results. You can now search:
    • In the whole project which now includes files in the Project Organizer.
    • In any given folder.
    • In files by name, for example, you can search *.flsnp for all snippet files or t*.* for all task files, if you adhere to such a file convention.
    • For whole words which omits partial matches in longer words.

    You can now also save search results in a CSV file which is helpful if you need to work on results over a longer time.
    Note that Replace All has become less transparent! Previously, this function would open all files with matches, apply the replace, mark them with the “edited” asterisk and save them. In Flare 10, Replace in All Files will silently replace matches in all files currently not open. This is much faster, but there’s no asterisk, no undo, and you don’t even see the replace.

  • Word count reports per topic and project. Many of my topics get translated, and our translators need to know how much I’ll send their way. With the new word count reports, I can give them an indicative estimate a few days before I finalise my work and send it off. The Report Editor in Flare 10 now has a Content Files > File Word Count report that counts each file in the Content Explorer, whether it’s an actual topic or a snippet or a template:

Word Count Report in Flare 10

There’s also the Project > Statistics report which counts all words in a project – which is especially useful in connection with the customised project export mentioned above.

  • Locate in TOC has gotten better. This function finds the selected topic in a table of contents. I use this a lot as I switch back and forth between the back-end topic structure in the Content Explorer window and the users’ view in the table of contents. I can now right-click a topic in the Content Explorer and go straight to Locate in TOC without going through the XML Editor or the Link Viewer. This makes my navigation even faster.
  • File preview data at the bottom of the File List, Project Organizer and Content Explorer windows shows details of the selected file. First are the file name, which is redundant, and file type, which I usually know, so that is not very useful yet. The second column shows Date modified which can be helpful. But with long-ish file names, I never see the second column in the narrow, docked windows. So this is a good idea with questionable results. I’m also worried that it will slow down navigation in folders with lots of files, but I have no proof for this.
  • Searching in source code now gives faster access to the topic in the XML Editor thanks to an added button.

For more information, consult these MadCap resources:

What do you think are the most impressive enhancements in Flare 10? And where have they come up short?

What’s new in MadCap Flare 10, the hip parts

Flare 10, the annual major release of MadCap’s flagship Help Authoring Tool, includes several major enhancements that make Flare easier and faster to newcomers and editors of marketing content. And many smaller enhancements target the hardcore techcomm heavy users. The well-balanced improvements testify that MadCap listens to many of its users.

Today, I’ll focus on the more obvious strategic enhancements. A second post covers the enhancements that I enjoy most – many of them are smaller improvements for heavy-duty tech comm users with large projects and many topics.

Out with the geek

Many major changes aim to make Flare more attractive and easier. For the longest time, Flare carried the reputation (some say: stigma) of a steep learning curve. Flare 10 goes a long way towards flattening that curve to help you get going faster. In a way, it means Flare has been de-geekified – and I’m sad to say that the nicely geeky propeller hat logo went into hiding as well.

  • The new Start Page offers new output templates as soon as you open Flare to get you started:

Flare 10 Start Page

The new templates mainly support the recent trend of merging technical and marketing communications. They offer formats such as product brochures from 3- to 6-fold layouts and slideshows. I rarely create new projects from scratch, so this isn’t for me. I mainly need the Start Page to re-open previous projects which I can still do.

  • Support of desktop publishing is probably better than ever, thanks to the improved page layout editor and the new support of Open Type fonts. Encroaching on desktop publishing products such as InDesign by rival Adobe, Flare has some strong arguments with its ability to reuse content in tech and mar comm. Since I don’t use DTP products and don’t create mar comm, I cannot judge how convincing Flare ultimately is in this arena.

In with the hip

Two enhancements in online output benefit tech comm and mar comm alike.

  • Slideshows present a gallery with horizontal page-by-page navigation as opposed to vertical scrolling:

Flare 10 slideshow example

Slideshow pages can show images, videos, workflow stages, etc., along with descriptive captions and auto-play support. Thumbnails or bullets aid navigation. I really like the slideshows and expect to use them mainly to illustrate or guide users through multi-step workflows. I can also imagine drilling down from a process overview to the individual stages on slideshow pages.

  • Responsive HTML 5 output ensures that output resizes automatically to fit mobile and tablet devices, see above. We had entertained the idea of creating separate EPUB targets for tablets, but the flexible responsive HTML5 output is of course much more convenient. It’s another good reason for us to move to HTML5 soon.

For more information, consult these MadCap resources:

What do you think are the most impressive enhancements in Flare 10? And where have they come up short?

Follow

Get every new post delivered to your Inbox.

Join 729 other followers