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.

Advertisement

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.