A day in a tech writer’s life

In a typical day of my working life, writing takes a backseat to collaboration and communications. – This article first appeared as an “A day in the life” column in ISTC’s Communicator in the Spring 2011 issue, page 58. I really enjoy the “A day in the life” pieces, because they’re like chatting with fellow tech writers about their day at the office. So I was honored and proud to write one of the instalments, and I hope you enjoy it.

A day in the life

It’s an ordinary spring day, and I wake up in Frankfurt, Germany. When I’m lucky, the sun shines into my apartment to greet me. My morning routine is woefully brief, and I take a train to Bad Homburg shortly before 8am. The commute is pleasant since I live in the city, but work in the suburbs.

Frankfurt skyline, as seen from the Main river bank

Frankfurt skyline from the Main river bank

I’m a Senior Technical Writer for SimCorp, a Danish company that develops and markets the investment management system SimCorp Dimension to banks, insurance and fund companies.

I arrive at the office around 8:30am. I’m the only full-time writer in the German office, though a tester across the hall writes part-time. Ten writers are based in Copenhagen and Kiev.

I start up the PC and get a cup of tea. I receive an email from a colleague who has found an error in the online help. I check with the developer; my colleague is right. I check it against the Release Notes. This is embarrassing, they contain the same mistake, nobody had caught it. The Release Notes have gone out already, but at least I can correct the online help for the next release.

Next, I check the Solutions database, which is what we call our FAQ collection. We technical writers are responsible for editing the entries and aligning them with our documentation. A consultant has created an entry with a workaround. That’s odd: the Solutions entry does the trick, but we should really just fix that exception! I consult with the developer who will fix the bug. We will publish the Solutions entry for the time being and delete it in the next release.

It’s 9:30am, and my testing colleague asks for my opinion. She is about to finish her first manual and has created a list of index terms and wants my opinion on them. Also, the Word template for manuals has become corrupted somehow, so we need to fix the page headers, which are supposed to show chapter numbers, chapter headings and page numbers. Her index looks good, so we agree on it very quickly. Then we wrestle with Word for a while.

At 10am, it’s time for a video conference with the Copenhagen headquarters. I’m one of four people developing the future documentation strategy. We’ve already sketched out the processes on how we want to work in the future to implement structured and topic-based authoring.

Today, we discuss a design for an information model that I’ve drafted. I’ve basically taken a subset of DITA 1.1 and mapped its topic types and elements to our documentation contents. My colleagues have been reviewing it before the meeting, and they point out some parts that are inconsistent or confusing. Also, our model is still missing a couple of metatags, which means that my task until our next meeting will be to clarify some sections and to add the metatags. The video conference ends at noon, so I can catch my German colleagues as they head down to the cafeteria for lunch.

After lunch, I find an email by a colleague writer. I’ve agreed to review his manual, and here it is. The review is tricky since I don’t know a lot about the module he describes. SimCorp Dimension is a fairly large and complex wall-to-wall system, so not every writer knows all modules in detail.

We had agreed that he’ll need another reviewer for the actual contents, but I can still help him with the chunking of topics and the manual structure. I propose to change the nesting of topics in a couple of places. Also, the topic headings aren’t fully consistent yet. I hope he will find my suggestions helpful.

Reviewing the manual reminds me that I still need to find reviewers for my own manual that is just about finished. I can always count on the product manager (if he can find the time), but I like to have one of the implementation consultants review it as well. They know our customers and their workflows best from implementing the product on site, so their reality checks are invaluable.

At the same time, it’s often tricky to find someone who can spend one or two days away from a project. It helps that they find the manuals generally useful. I approach the team leader and tell him when the manual will be ready and that it will take 6 to 8 hours to review. He has a couple of colleagues in mind, but needs to check their schedules. He will get back to me.

It’s 3pm, and I start to actually write documentation. I continue to write Release Notes for the upcoming release. That means I go through all the development efforts in the tracking system and briefly document the enhancements and their benefits.

In between, I come across one enhancement where it is not clear yet whether it will actually be included in the upcoming release. I contact product management and, indeed, it’s not been decided yet. That makes me nervous: in the previous release, some of these decisions came awfully late and required some last-minute editing.

Though I started writing rather late, I make some good progress. Around 5pm, I call it a day and take the train home. When I’m lucky, I can see Frankfurt’s skyscrapers shimmer silver in the setting spring sun.

Your turn

How much time to do you spend writing, as opposed to communicating? Is this similar to what your days look like? Feel free to leave a comment.

Advertisements

A pattern library for user assistance

Rob Houser is working on a Pattern Library for User Assistance (UA): At WritersUA, he proposed to collect examples for patterns in (embedded) user assistance to help teams and managers with whom UA professionals collaborate to better understand the benefits and value of UA. Among UA experts, it can help to establish and exchange standards by deducing principles and concepts from them.

Rob Houser explains the pattern library for user assistance

Rob Houser at WritersUA

UA patterns can be organized by the task they support, whether it is helping users to get started in a new application or task or to assist them in the correction of errors. A fairly well-known example of the first case is Internet Explorer’s help text that appears when you open a new, empty tab. Such a pattern can support users in:

  • Understanding conceptual information what has happened, what options the user has, when to use this function and why.
  • Make decisions by providing context, reference information about rules as well as hints for best practices.
  • Solve problems by describing the problem, showing how to fix it, give background information, if available, and show how to avoid the problem in the future, if possible.

Such a library will be really helpful, because it will fill the gap between very formalized, but abstract topic types (concept, task, reference) as DITA models them and the wide variety of UA that’s actually “out there”.

With a community effort of collecting and annotating patterns, such a library can be a qualified, curated collection of best practices in UA that can help tech writers write better help faster by following tried and proven examples.

So I agree with Rob’s approach and think such a pattern library would benefit a lot of people. Personally, I can’t wait to start and deduce the underlying principles and concepts of sucessful UA patterns. While examples can be instructive, I prefer to work in more abstract terms. This would also square better with the general approach in UA to separate content from style. After all it shouldn’t matter whether UA is provided in the actual user interface (where real estate is often scarce, esp. in mobile applications), in a tooltip or in a separate window.

Chuck Martin also blogged about this interesting session. I’ll be following Rob’s efforts and report when there’s new developments.

Your turn

Is this something that would help you as a tech writer or UA professional? Would it be instructive to have annotated examples of best practices in user assistance? Please leave a comment.

15 things I learned at WritersUA

WritersUA brought many small epiphanies, quick bursts of insight, that I’d like to share. From each session I attended, I present a tasty morsel that whets the appetite, that’s meant to be shared. It also gives you an idea of the breadth – and occasional overload – of information at the conference. (Of course, the sessions also offered much more substantial lessons than these, but they will take me a little longer to digest.)

But for now and as a tribute to going dinner with the conference crowd to a restaurant called “Sevilla”, here are:

Tech-Comm Tapas in Long Beach

  • Much of “CSI: Miami” was or is apparently filmed in Long Beach, from Let’s Look in the Mirror and See What We See with Matthew Ellison, Tony Self, and Joe Welinske.
  • A pattern library for user assistance can help to disseminate best practices and establish standards for user assistance design, from A Pattern Library for User Assistance with Rob Houser.
  • To bridge cultural differences in a global, distributed team, mutual trust and respect beat everything else, from Global UA Guidelines and Requirements with Pam Noreault.
  • Documentation and training may share contents, their goals are at odds: Documentation constitutes an external knowledge repository, while training aims to build an internal knowledge repository. That makes it a little harder to reuse contents, from Opportunities for Reuse between UA and Training with Linda Urban.
  • When switching to a new tool, get every writer a license as early as possible, so they have plenty of time to get used to it and play around, from Double Scoop Case Studies about MadCap Flare, with Denise Kadilak.
  • As one of their single-sourcing methods, Flare supports global project linking. This allows you to share and inherit just about any file across projects, including topics, from Double Scoop Case Studies about MadCap Flare, with Patrick Calnan.
  • Single sourcing documentation for multiple (similar) products and content reuse can reduce content by around 30% and reduce yearly efforts by almost 50%, from Double Scoop Case Studies about single sourcing, with Deb Woodcroft.
  • The paid version of SharePoint includes a translation management feature which automatically creates copies for each language and lets you assign tasks to translators, from A Realistic Approach to Content Management with SharePoint with Dan Beall.
  • The 7+/-2 rule was never meant for the optimum number of steps in a procedure. It comes from a study about how many random things people can remember for a short time. Instead, the optimum number of steps is (usually) less than 10, but for different reasons, from Help Procedures That Work with Leah Guren.
  • Ensuring accessibility of web sites and documentation for people whose physical and/or mental capacities are restricted is not an issue that affects “them”, it affects us, specifically each one of us who is aging, from Making Your UA Accessible to All by Shawn Henry.
  • If you create an operating system, make sure the name doesn’t undermine your efforts: Windows CE (“wince”) and OS/2 (“OS half”) will come back to haunt you after years when they appear in The Geek Trivia Quiz Show.
  • When you create podcasts, ensure you make your audience part of the conversation – talk with them, not to them, from The Art of Podcasting with Omaha Sternberg.
  • Trying to create PDFs from DITA with open source tools may make you look less sophisticated than you are, from What They Won’t Tell You About DITA with Alan Houser.
  • During a phone interview with subject-matter experts, simultaneous chat is the perfect way to keep and verify notes and to add screenshots on the fly, from Strategies for Working with Subject Matter Experts with Susan Becker.
  • You can use “elements of surprise and fear” (obvious Monty Python reference that wasn’t in the session) to remember where you put your keys: Wherever you put them, imagine that place explode as the keys hit, Tickling the Brain: Sharing Ideas in Memorable Ways with Adam Rubin.

Thanks for the insights and the memories, everyone!

If you’ve been to WritersUA, feel free to share your favorite tapas-like takeaway in the comments.

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 at the MadCap roadshow

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.

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.