UK MadCap user group launches with two events

MadSIG, the MadCap UK & Europe user group, launches with two events in the UK in September. We are a handful of MadCap users who network to share expertise and support. Most of us are based in the UK, though I’m the Europe outlier who’s based in Germany (and sometimes Denmark).

MadSIG offers occasional meet-ups and also a LinkedIn group for feedback, ideas and resources. If you are a sole technical author, become part of a more personal group – in your own virtual home town rather than in the big city of the online forums!

MadSIG is a special interest group under the ISTC‘s umbrella – while you don’t need to be an ISTC member to join and participate, it’s certainly a good idea to take advantage of the society’s many benefits.

Meet with MadCap’s Mike Hamilton in Staines on 19 Sep

Mike Hamilton from MadCap is going to be at the Swan Hotel and Pub, The Hythe, Staines TW18 3JB, on Thursday 19th September from 7pm onwards. He’s generously offered to spend the evening talking MadCap with anyone who uses Flare and the other MadCap products, or is interested in finding out more about them.

If you would like to come, please let us know by email to MadSIG@ISTC.org.uk with your contact details, so we can update you if anything changes last minute. If you’ve got any specific topics you’d like to talk about, feel free to let us know, too.

Mike Hamilton has an encyclopaedic knowledge of the MadCap products, so bring your questions and, if you like, your projects, and get to know some other Flare fanatics from the South of England at the same time.

Inaugural MadSIG meeting at TCUK on 25 Sep

MadSIG holds its inaugural meeting at TCUK 2013. If you’re at TCUK anyway, this is your easiest chance to meet other MadCap users. We’ll meet at the Terrace Bar of the Marriott conference hotel on Wednesday, 25 Sep at 5 pm.

This meeting is a TCUK fringe event – that is, it is organised by us delegates, not by the conference itself. We are grateful that TCUK provides space and publicity.

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:

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… 🙂

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.

ROI of topic-based authoring and single sourcing

Breaking down content silos brings benefits and ROI to topic-based authoring, even if you have little or no translation. I’ve cut down time to write and maintain three deliverables by 30-40% by reusing topics.

Content silos

The company I work for supplies documentation for its software solution in different formats, among them:

• Release notes inform customers about new features and enhancements in new versions.
• User manuals describe individual modules of the product, how to set them up, how to operate them and what kind of results to expect from them.
• Online help focuses on reference information for windows and fields, but has some overlaps with information in user manuals.

Originally, these three deliverables were created and maintained in separate “content silos”, using separate tools and separate source repositories. So the documentation process looked like this:

1. Write release notes in Word.
2. Update or write user manuals in Word.
3. Update the online help in a custom-built help tool that uses Word as an editor and Microsoft’s HTML Help Workshop to publish to Microsoft Compiled HTML Help (.CHM).

I’ve found that I could save some time by writing the release notes with the other deliverables in mind, so I could copy and paste content and reuse it elsewhere. For example, my release notes describe a new batch job which helps to automate a tedious workflow. If I describe the batch job in detail, the same content fits easily into the user manual. (Yes, it bloats the release notes, but at least the information is available at the release date, while we didn’t always manage to update the user manual in time.)

Copying and pasting worked even better once I structured the content in each of the three silos as topics. For example, a task topic from the release notes would fit almost gracefully among similar task topics in en existing manual.

But such manual copy-and-paste reuse is really not efficient or maintainable, because my stuff is still all over the place. I may write in – or copy to – four places, but then remember to update only two of them; enter inconsistency and its twin brother unreliability.

Getting real about reuse

To get the full benefits and ROI of topic-based authoring, we’ve found it’s not enough to simply write topics and keep your concepts separate from your tasks. We’ve had to adjust our documentation architecture, our tools and our process.

The guiding principle is: “Write once, publish many”. This tech comm mantra proved to be the key. We now aim to have each piece of information in only one topic. That unique topic is the place we update when the information changes. And that’s the topic we link to whenever a context requires that information.

Single sourcing is the best way to get a collection of unique topics into user manuals and online help. So we needed to consolidate our separate content silos into a single repository from which we can publish all our deliverables.

MadCap Flare is the tool we chose. It gives us a reliable, yet flexible way to maintain a common repository of topics. For each deliverable, such as release notes and user manuals in PDF and online web help, we simply create a new table of contents (TOC) which collects all topics that go into the deliverable.

The writing process has changed considerably: Previously, I would focus on writing a release note entry or a chapter in a user manual. Now I find myself focusing on a specific task or concept and how to describe it as stand-alone content so it works for the user, whether it appears in a user manual or in the release notes.

The flexibilities of MadCap Flare’s conditions feature and of our DITA-based information model help us to accommodate the differences of our deliverables. We still write a few topics explicitly for a specific deliverable. For example, in release notes, short “glue” topics serve to introduce new concept topics and task topics to establish some context for the user and explain why a new feature is “cool”. In user manuals, an introductory chapter with a few topics explains what to find where and which sections to read for a quick start.

But most of the topics can now be used in release notes, user manuals and online help alike. Since I’ve gone from copy-and-paste in three content silos to single sourcing topics in Flare, the time to write and update documentation for my module has decreased by 30-40%. It’s on the lower end if a new version brings a lot of brand-new features. It’s higher if there are more enhancements of existing functionality.

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.

Alice Jane Emanuel’s “Tech Author Side Rule” at #TCUK11

Technical Communication UK 2011 is off to good start with around 100 people attending six pre-conference half-day workshops on Tuesday. Even the night before saw about 20 attendees joining the organisers to help with last-minute setup chores, not to mention drinks and dinner.

On Tuesday morning, I attended Alice Jane Emanuel‘s workshop “The Tech Author Slide Rule: Measuring and improving documentation quality“. In a lively and engaging session, “AJ” taught us how to use the slide rule she came up with. It is actually an Excel spreadsheet that helps you measure qualities such as structure, navigation, language, and task orientation. You weigh a good 30 or so of such qualities in documentation, depending how important they are to you. Then you can grade a document (or a collection of topics after optional tweaking) by assigning points for each quality. The sheet sums up the weighed points per category and also for a total score.

AJ Emanuel, with David Farbey, before explaining the Tech Author Slide Rule

While the sheet is excellent to track progress over time, you can see results very quickly by comparing your current documentation with legacy deliverables. The quantified approach offers a range of benefits that are otherwise hard to come by for tech writers:

• The numbered scores appeal to managers and make to easier for writers to show progress and accountability.
• The standardized categories can help you to build a team by ensuring that everyone focuses on the same qualities and by pointing to problems where individual documents go off the rails. They also help to train new writers.
• In general, it helps to raise the profile of technical communication by clarifying its contribution and giving everyone in the organization more specific terms and numbers to discuss.

AJ emphasized that you need to keep the tool’s categories and usage consistent: It’s fine to change or add categories, weights and ranges of available weights and scores, but remember that you jeopardize comparability of results when you do. It may be fine to add a handicap for special cases, but in general, beware of grade inflation and keep your grading consistent.

I think the tool is a great addition to any peer review/editing process when fellow tech writers assess style guide compliance. Given it’s granularity of dozens of weighted criteria, I expect it would be most valuable to improve writing that’s problematic in specific categories. When different writers assess the quality of different deliverables over time, I’m not sure if the grading is consistent enough and the one total score is indicative enough to track progress in a meaningful quantifiable way. However, I believe it could still show relative improvement.

I think it’s very much worth checking out AJ Emanuel’s slide rule, and it’s easy to test drive it:

1. Download the tool from AJ’s website Comma Theory where you can also find additional information.
2. If you want to, tweak the categories (for example, by comparing it with Gretchen Hargis’s qualities in her book Developing Quality Technical Information: A Handbook for Writers and Editors.)
3. Quickly grade a (short) document in a legacy version which has since seen significant improvement and in the current version.
4. Evaluate the scores and test them on colleagues or managers.

Favorite tech writing dogmas

I’m usually wary of dogmas, but some just won’t go away, they assert their eternal truth in uncanny ways. I’ve recently found some new ones, so I now have four five tech writing dogmas:

1. A new tool will not fix broken processes.
2. No matter how cool you are as a software company, don’t build your own help tool – it’s not worth it.
3. Don’t invent yet another universal standard. – from xkcd’s How Standards Proliferate
4. Following a style guide will not make you a good tech writer (unless you understand methods and processes such as topic-based authoring and single sourcing as well) – from Scriptorium’s The latest style for tech comm: adding value
5. “No matter how much you try, you can’t stop people from sticking beans up their nose.” (This metaphor can apply to customers who use your documentation or to non-documentation managers who make decisions about documentation.) – from Jared Spool’s highly entertaining and insightful post

Your turn

What do you think: Are these some of the eternal truths in the world of tech writing? Have you encountered them? Or are dogmas inherently silly and evil? Please leave a comment.

All aboard! Onwards to structured authoring!

Our team of technical writers is embarking on a journey towards structured authoring. With 10 writers, we’ll move from an unstructured Word to PDF/CHM environment to a structured Flare to WebHelp/PDF environment. Or I should say “semi-structured”: We do have an information model based on DITA, but we won’t actually be able to enforce it with Flare (which we knew before we chose the tool).

It’ll be an interesting cruise, to be sure! Four writers already apply topic-based authoring rather than the previous free-form documentation guided mainly by common sense. The others have had training, but no real opportunity to write topics continuously. We have drafted tighter new processes to draft, write, review and edit topics to replace the previous loose processes of writing and reviewing, but they are not in place yet.

And then there’s the new tool, of course. Only one of us has worked with Flare before. Many of us are excited about getting Flare. Some really like it – what we’ve seen in several demos so far. Others just really loathe the current writing environment.

“Regarding the pain of others”

So as we’re about embark, I’ve been looking out for others who’ve taken the trip before. Scriptorium’s State of Structure webcast has been very helpful: Its results of a survey among 200 tech communicators helps to position us in relation to others who are currently implementing structured authoring or considering it. It also collects some mistakes respondents have gone through. I’ll just be quoting a few select points, but the whole webcast by Sarah O’Keefe is totally worth checking out, so thanks to Scriptorium for making this webcast available!

Reasons

The top reasons why survey respondents (consider to) move to structured authoring made us nod emphatically: Reuse, consistency and cost savings are also at the top of our wish list of achievements. Looking ahead, it’s promising that the majority of respondents achieve these goals.

We’ll also take other goals that respondents achieved, whether it’s to automate processes or to reduce content (oh, yes, please, we’re not even exactly sure how much redundant, almost identical content we have). So far we’re confident, we’re not only doing the right thing, but doing it for the right reasons, too!

Efforts

Savings have their own price, of course. Sarah’s survey confirms several cost points we’ve already identified in the project.

• Converting legacy content is a biggie for us, simply because we currently have a lot of stuff.
• Redefining output layout will take time, but will be worth it given what Flare is capable of doing with CSS in both web and print outputs.
• Integrating a new system with its writing and publishing processes into our product and workflow systems will also take some time.

Mistakes

Mistakes have been made by others before us, and we’ll have plenty of chances to make our very own mistakes. If we’re lucky, we can avoid repeating the mistakes of others:

• Planning and project management cause problems, maybe because most companies lack the experience of major documentation overhaul projects. Sarah specifically mentioned the lack of understanding of the project scope and of the need for testing. So we’ll look through our project plan again and ensure that the estimates are plausible.
• Converting legacy contents can also get you into trouble, especially when you convert something that’s less than structured. It doesn’t help if you reserve too little time to do it or get inexperienced people to do, whether it’s off-shore labor or student helpers. That’s sound advice: GIGO (“garbage in, garbage out”) can certainly endanger the expected benefits. A new tool can help us be more efficient, but we still have to learn and apply structured writing in topics. So this confirms one of my two tech comm dogmas: Don’t get a new tool to fix your processes!

Setting out

What do you think? Is our crew well-equipped, given a tried and proven method, well-defined processes, a new tool and the words of warnings above? If you have additional advice, please leave a message.

Top 5 things I like about WritersUA

WritersUA is a very stimulating and inspiring conference! This year’s 19th annual conference draws 360 attendees (speakers included) which makes it the largest tech comm conference I’ve attended so far. Kudos and compliments to Joe Welinske and his whole team who simply “get it right”.

Here are the top 5 things I like about WritersUA:

1. Great program, good pace

An online community on the conference web site allows attendees to connect as much or as little before the conference as they like. The program is paced very well: At 60 minutes, sessions are long enough to be thorough and leave time for questions and discussions. 20-minute breaks between sessions allow for several contacts with attendees and/or exhibitors.

2. Proceedings are available before hand

At first, I was overwhelmed by the package I received at registration, but it makes sense: Looking through the slides allows you to make the best possible decision which session to attend. Even if several presenters have edited their slides after submitting them for print, but the earlier versions are always a good, reliable indication. Initially, I had selected sessions by my general interest in the topics. After reviewing the slides, I changed my schedule for Monday completely. One session looked more basic than I had expected, and the slides are so comprehensive I couldn’t imagine I would miss much (and from what I heard from attendees I didn’t).

3. Sessions that are worth attending – in person

I got the most out of sessions that offered constructive discussions in addition to mere presentations:

• Rob Houser presented a “community-works-in-progress”, a Pattern Library for User Assistance, where we discussed whether this was something worth having, whether we could imagine contributing to it and how to best go about it. (For more information, follow the link above, see Chuck Martin’s write-up or watch this space for a more elaborate review.)
• Linda Urban described and analyzed her experiences with Opportunities for Reuse Between User Assistance and Training and invited a discussion which was very enlightening: Even between two such closely related domains, different cultures, organization, budgets and deliverables make it difficult to break down the silos and to collaborate successfully.

4. Comprehensive look at help authoring tools

WritersUA offers a unique combination of first- and second-hand experiences to compare tools in depth.

The exhibition area at WritersUA

• In the exhibition area, most of the relevant vendors are present among the 14 exhibitors and more than willing to present their products in the best possible light.
• In a lab, attendees have access to most of the relevant tools at workstations. You can just play around with them or visit at a time when a vendor is at hand to ask questions (though these are not presentations).
• And during the meals and breaks, you can ask other attendees about their experiences with the tools.

5. Great gathering of passionate, fun tech writers

As early as Saturday afternoon, I met friends from previous conferences and people who’s writing, blogs or tweets I’ve seen online. The various networking opportunities make it easy and fun to strike up a conversation, trade travel stories, share frustrations about clueless managers or absurd processes or quote obscure Doors’ songs.

– So far, WritersUA has been a great example of my Top 5 reasons to attend a tech comm conference. If you’re attending WritersUA or have attended a tech comm conference in the past, feel free to share what you liked best about them in the comments.

MadCap roadshow in Long Beach

MadCap kicked of the 2011 season of roadshows on March 13 in Long Beach, CA, to coincide with the workshop day of the WritersUA conference.

A full-day program offered primers on topic-based authoring and single sourcing, best (and less recommended) practices of collaborative authoring, and a passionate introduction to Cascading Style Sheets (CSS). Shorter breakout sessions (which don’t seem to be part of the other roadshow dates) presented tips and tricks for Flare: How to handle tables, create print output and localize, as well as a case study about moving from RoboHelp to Flare.

Mike Hamilton reminds us to think topics!

More like a conference

Several aspects made the event feel more like a Flare-centric conference than the marketing or sales event it was as well:

• Presentations address tech writing challenges in general, whether or not you use Flare:
  • How to optimize topics for reuse
  • How to efficiently publish to several media from one source
  • How to collaborate with other authors.
  • And, oh yes, how you can do these things with Flare. But the general emphasis was on: “Here’s how you can work efficiently.” In fact, the helpful introduction to CSS didn’t rely on Flare at all. The more sales-y “Wanna see what the new version can do?” came only in a longish rock video with MC Mike during the drinks reception.

• Networking opportunities galore during breakfast, lunch, the concluding reception and to some extent even during the breakout sessions.
• A day’s worth of Q&A. MadCap brought more than a dozen people from all teams to be able to answer any question that we present and future users might throw at them. Their answers were usually constructive and frank, though my question about the number of employees got the PR-tinted answer “fewer than 100”. When asked whether Flare can do X, Mike sometimes says: “Not at the moment.” Previously, I thought this was just supposed to sound better than “No.” But after following Flare’s development for a few versions, I now see that many of such features have been added, such as the long-awaited formula capabilities in version 7.

Taking tech comm seriously

In a nutshell, MadCap continues to take tech writers, their requests and issues seriously. Here are some examples of insights from the sessions to illustrate how they go beyond the bells and whistles of selling a new version:

• Customer focus is important – but documentation must also recognize and satisfy the owner (usually, the company that pays for the documentation) and the manager (who needs to ensure that documentation is completed in time and in budget).
• Create separate target definitions for separate deliverables. Don’t rely on manual steps in the production process which might get lost in the hustle and bustle. For example, don’t trust that you’ll remember to update the global variable with the correct company name…
• When you share source files over a network, even in a small team, use either a dedicated source control system or SharePoint (which includes source control) which avoids two people editing the same file at once and allows to lock down central resources like stylesheets.
• There is no one font size that’s always appropriate. How large a font appears depends a lot on the “x-height” (roughly the height of the letter x), and that can vary in fonts of the same size.

Wish list

Taking my cue from other conferences I’ve attended, I think MadCap could add two things to improve the roadshow:

• Book table. There are a few books available about MadCap products. For those of us who like books with their tools, why not have at least a sample copy by the registration table, so we can check them out whether we want to buy them or not?
• Rant & rave session. This one might not be in MadCap’s best interest, but hey, they’re generally a pretty accessible company who like to collaborate with their customers and prospects. I think they should put on a session where attendees can get one minute each to rant and/or rave about the products. Such a forum would give MadCap a quick way to see what bothers a lot of users – and what they like. Two peeves came up:
  • The previously free reviewer module “X-Edit” has been replaced by “Contributor” which requires a license per user. This is not feasible in environments where each writer easily has one or two dozen potential reviewers. MadCap needs to come up with a better licensing model for this.
  • Flare lets you define separate CSS Mediums for print and online in great detail. A field near the top indicates which one you’re editing. Yet a lot of users still manage to edit the “wrong” one when they get all engrossed in styles. Simply highlighting this better would improve usability for focused, single-minded users.

If you’ve attended a MadCap roadshow or other such industry event or are considering to attend, feel free to share impressions or questions in the comments.