Getting mileage from a tech comm mission statement

If you have a mission statement for technical communications, you can use it to anchor several strategic and tactical decisions. I’ve suggested a few general reasons Why you need a tech comm mission statement in my previous post. The valuable discussion that ensued led me to think we can get some mileage from a mission statement in some high-level tasks further downstream.

Consider a mission statement that says: “Our product help provides users with relevant product information at the right time in the right format.”

Defining audiences and deliverables

You can keep your audience in focus with a mission statement. Do you write for end users? Maybe there are different types, such as professionals vs. amateur hobbyists? Do you also address colleagues who expect to find internal information in the documentation? The mission statement above doesn’t specify it – and hence can be expected to address everyone who uses the product.

You can also derive your deliverables from a mission statement. Do you publish to several formats or only to one? What is your priority of formats? Web help first, PDF second seems a standing favorite that’s recently been disrupted by the emergence of mobile output. The mission statement above merely mentions the right format – so you need to figure out what format is right for your audience types. You can use personas to determine how your users work with the product – or better yet: Observe or survey them!

Defining information model and processes

You can derive your information model, the structural standard of your documentation, from your mission statement. This model should help you to reach the goal described in your mission and serve your audience. For example, topic-based architectures have long been popular. If you need to retrieve small chunks of information, for example to share steps in a task or exception handling advice, consider a more granular standard such as DITA.

Your processes should outline a repeatable, efficient and effective way to create your deliverables so they address your audience and, once again, help you to achieve your mission goal.

Your information model can suggest which topics or elements to create need to be created and updated for a given product or enhancement. Together with your processes, this makes it easier to plan and estimate documentation efforts – in theory at least…

- But with some management support and some persistence, a mission statement and some strategic decisions piggy-backed on to it can help you get out of the proverbial hamster wheel.

What do you think? Can this be helpful? Or is it too far removed from real life? Do you have any experience with a larger documentation strategy based on a mission statement? If so, did it work?

Why you need a tech comm mission statement

A mission statement for technical communication can help everyone in your company (or you and your customers) to stay on track in pursuit of a common goal of what your documentation can and should achieve.

Just like a corporate mission statement, a tech comm mission gives all parties who are involved with documentation direction and a common goal. It describes the purpose and benefit of the documentation and how it is achieved. It helps to define processes for creating the documentation as well as metrics whether the documentation is successful. If the mission is well-conceived, it guides documentation strategy without prescribing it.

For example, if you want to focus on usability and speed, a mission for your documentation could be: “Our product help answers any user question about product use in no more than three mouse-clicks.” Your strategy would then aim for a well-structured, easily navigable context-sensitive online help – with printed user manuals and closely tied in training materials taking a backseat.

A more comprehensive mission could be: “Our product help provides users with relevant product information at the right time in the right format.” This would set you on a quest to find out who your user types are, which product information is relevant for them and which formats it can be provided efficiently.

A mission statement in itself cannot be right or wrong. But it must be useful in several respects. Specifically, it must help:

• Your customers and users by guiding you to provide useful documentation.
• Your company externally to provide documentation which improves the perceived product quality.
• Your company internally to anchor the importance and function of documentation.
• You as technical communicators to make appropriate strategic decisions about documentation, for example, which users to address, which deliverables and processes to define, which methods and tools to apply.

What do you think? Is a mission statement for tech comm necessary? Or merely helpful? Or a vain attempt at putting on corporate airs when the writers should just buckle down and get the job done?

Top 6 reasons to consider speaking at TCUK 2013

TCUK 2013, the UK’s premier tech comm conference, has just opened its call for proposals – and here are some good reasons why you should consider applying to speak in Bristol in September!

What all reasons have in common is that technical communication as a field and TCUK as a conference are more versatile, lively and interesting than you may imagine!

Consider speaking because you…

1. Manage a tech comm team, project, migration or strategy. This year’s specialist stream is “The Management of Technical Communication” in all its variety. TCUK reacts to one of the industry’s megatrends of recent years which is to position tech comm, even within corporations, as a business which can prove ROI.
2. Commission technical communication. – That’s right: We technical communicators want to hear from people who engage tech communicators, in fact, we need to! One of tech comm’s mantras is “Know your audience” and that definitely includes those who ask us to create documentation in the first place.
3. Have something to share, even if you haven’t spoken at a conference before. TCUK is very welcoming to newbies! I know, they gave me my first speaking opportunity in 2010. And I have attended TCUk ever since and seen two newbie presentations last year which were met by a supportive audience.

Consider speaking because TCUK is…

1. A top 3 tech comm event in Europe. TCUK is the best opportunity to network, catch up with trends, trade experiences, mull over challenges, along with tekom in Germany and UAEurope in different countries.
2. Cozy and diverse. In my opinion, TCUK is the perfect combination of a cozy scene and a wide range of topics. It offers stimulation and inspiration of larger conferences without the intimidation that a dozen streams and several hundred participants bring.
3. Free for speakers! However, you will have to arrange for travel, accommodation, and meals yourself.

And if you don’t think you have enough for a 40-minute talk, you can still save the date and hold out for the annual “open stage” rant session. It’s not been finalised yet, but there was such a session for the last 3 years. All of the above reasons and benefits apply, except for the free conference attendance.

Just the facts, please!

• TCUK 2013 takes place 24 – 26 September at the Bristol Marriott City Centre.
• You have until 5th April to propose 40-minute talks or 3-hour workshops.
• See the call for proposals for details about topics and formats.

EPPO redux or: Mark Baker is on to something

“For users, Every Page is Page One,” says Mark Baker. Users can land anywhere in your documentation and start consuming away. That’s why structured authoring is more than one method among many – it’s an imperative to create meaningful content and to stay relevant as a technical communicator.

Few technical communicators have recently chipped away at unquestioned conventional wisdom as profoundly as Mark Baker in his blog Every Page is Page One (EPPO). Here’s his thesis in a nutshell – EPPO redux, if you will.

The following is my boiled-down edit of the session description of Mark’s workshop at the Intelligent Content Conference yesterday. I can only claim credit for the mistakes and misunderstandings I introduced, but everything below is essentially Mark’s wisdom. I share it because I find it sensible and highly relevant – if you do, too, I encourage you to follow Mark on twitter and on his blog.

Writing Every Page is Page One Topics
Mark Baker, President, Analecta Communications Inc.

For users, Every Page is Page One. So write good Every Page is Page One topics, even when you have a large amount of related subject matter to cover. Construct information so readers can meet their information needs, no matter where they land. When covering a broad array of subject matter, don’t design the information to be consumed sequentially or hierarchically like a book.

Successful Every Page is Page One topics

• Define a limited purpose: Do one thing per topic, do it well and completely.
• Stay on one level: Be broad or be specific in a topic, but pick one and stick to it.
• Establish context: Orient readers so they know where they are.
• Conform to type: Orient readers so they know what type of topic they see, help the writer be consistent and complete.
• Assume the reader is qualified: To help readers get qualified offer links in a topic, not details.
• Link richly: Encourage the reader to explore, anchor the topic in its context.
• Provide the big picture: Create explicit high-level picture, don’t bury the big picture in the htopic sequence or hierarchy.

Lessons from Ray Gallon on cognitive UA design

Context is everything: Support your users in their integrated competency learning and embed user assistance in the user interface and conceptual context in task topics. That’s in a nutshell what I took away from Ray Gallon‘s  webinar “User Become Learners”, the first in a series of 3 webinars on “Cognitive Design for User Assistance“.

To catch up before the second webinar on Tuesday, 29 January, read on or watch the recording made available by Adobe who hosted and sponsored the webinar (requires an Adobe ID) or check out Ray’s slides.

Evolving learning needs

What we need to learn changes all the time – it even seems to change faster these days. So for us technical communicators, says Ray, it’s not sufficient to show users how to use or learn a product. Beyond that, we need to teach users how to learn to adapt a product to their evolving needs.

To back up his claim that learning needs are not static, Ray showed OECD statistics for the last 50 years: In average European working days, routine manual tasks are down. Routine cognitive tasks way down. Non-routine manual tasks are way, way down. By contrast, expert thinking is way up. And complex communication is way, way up!

To help users meet these challenges, technical communicators need to offer decision support and to convey knowledge. Users need to be able to decide which problem they need to solve and if and how they can go about it. This requires knowledge: They need to understand contexts, underlying concepts and applicable tools. All this means much more than just explaining a product’s user interface – which would be routine manual and cognitive tasks that are on the way out.

How minimalism can help

Ray recalled the core principles of decision support, according to the U.S. National Research Council. Half of them relate directly to the tech comm principles of minimalism (as summarized by JoAnn Hackos on her blog recently):

1. Begin with the users’ needs in decision support; focus on users’ actions in minimalism
2. Connect information between producers and users in decision support; understand the users’ world in minimalism
3. Design for learning in decision support; ensure that documentation is findable and contains troubleshooting information in minimalism

Just because minimalism emphasizes hands-on practice doesn’t mean it shuns conceptual information, says Ray. So to add value to the documentation, describe applicable tasks, not just the user interface.

That means we tech comm’ers don’t just merely describe the menus and icons. Instead, we must also get involved in the design of the product, especially the interface with its labels and error messages and pop-up hints.

This way, usage of our documentation can improve drastically: Rather than supporting rote memorization or, worse yet, require users to look up the documentation repeatedly, users can learn from the documentation and apply what they find to decide what they need to do and how.

To carve up or synthesize?

One of the most important consequences of Ray’s paradigm for us tech comm’ers is that it effectively abolishes a dear dogma of topic-based authoring, namely the separation of concepts and tasks. Ray explains that just because we need to understand these areas separately (when we make sense of products during analysis) doesn’t mean we need to keep them separate when we present them again to users (during synthesis). Imagine a pizza: You need to understand crust, tomato sauce and toppings separately – but you would never serve them separately to the user. (For more about this, see Mark Baker’s blog post.)

For documentation, this means to empower the user: Read/understand once, apply many. I think the parallel to single sourcing is obvious and deliberate: Write once, use/publish many. Give users all the information they need – and only that, no more, nada mas! (And offer it in a way it’s findable immediately.)

Specifically, put conceptual information where it is most useful, into tasks. Integrating conceptual information into tasks avoids that concepts remain abstract and removed. In addition, progressive disclosure can help with the efficient embedding of user assistance into the user interface.

My lessons learned

I think Ray’s approach makes a lot of sense. It can improve many a help system that follows the letter, but not yet the spirit of topic-based authoring.

But two factors in my daily work dampen the effect of Ray’s ideas for me:

• We use a DITA-based information model which allows and in fact encourages contextual information as part of task topics. We want to ensure that users understand when they need to perform a task and why. I believe the <context> and also the <prereq> element in DITA serve this purpose well, without fully replacing concept topics.
• Ray’s assertion that “good user assistance is only needed once” is a bit too idealistic for many software products I have documented. Many are very complex, some are poorly designed to boot to allow the user to safely deduce a general principle about the product. So Ray’s paradigm does require not merely the technical communicator’s participation in the design phase, but actually good design. As Ray said during the Q&A session, “This is easy to explain, but hard to do.”

Top 6 tech comm trends for 2013

Flexibility in several dimensions is my tech comm mega-trend of the year, after mashing up the top 6 trends presented by Sarah O’Keefe and Bill Swallow in Scriptorium’s annual tech comm trends session. Head on over to Scriptorium’s site to watch a recording of the webcast and to read Sarah’s take on the trends she presented.

1. Velocity

Velocity is Sarah’s first trend which simply means that we tech comm’ers are expected to create, deliver and update content faster than before. Also gone are the days – or months – when localized documentation could be several weeks late.

If we are serious about this, we need to revamp our documentation processes. I agree with Sarah: A recent restructuring of documentation processes has sped up my throughput and made my estimations more predictable. So it has improved my productivity as a whole.

It’s also made me more flexible because my smaller task packages take less time before I finish with a deliverable. It used to take me 4 to 6 weeks to update a user manual, so interrupting this task for something more urgent was expensive because it further delayed the manual and also clogged up my pipeline. Now I take about 2 weeks for the same task which allows me greater flexibility in sequencing my tasks because I still have a chance to finish the manual by the end of the month, even if we decide that I first spend a week on something else. I could not have achieved this  flexibility without revamped processes to analyse and specify documentation and without a topic-based approach.

2. PDF is here to stay

Bill’s doesn’t see PDF go away any time soon, if only because it’s durable, controllable, reliable and downward compatible to that other durable format called print-on-paper. Google Docs might be a potential competitor, but Bill doesn’t see it making great advances on PDF in 2013.

As comments from the audience showed, there seems to be a lot of passion about the issue and some people can’t seem to wait to lay the last PDF to rest, finally. As a tech writer in semi-regulated industries, I know that I’ll be creating PDFs for my users for a looong time. It might not be a trend per se, but I agree with Bill that we haven’t seen the end of PDFs just yet.

3. Mobile requirements change technical communication

Mobile will be the big game-changer for tech comm this year, predicts Sarah. Requirements for mobile documentation mean that PDF will be one format of many – and maybe not the primary one in many cases. Other essential deliverable formats include HTML5 (for an online audience) and apps (for native or offline use).

The limited real estate of mobile devices requires more flexibility in how we structure and present documentation. Progressive disclosure can help us to integrate essential user assistance in labels or pop-ups. Beyond that, we need a strategy of what to disclose where and how to create a seamless and consistent user experience.

4. Mobile drives change

Similar to Sarah’s trend, Bill underscored the influence of mobile documentation. He emphasized the need for concise, no-frills content. Rather than jump on the progressive disclosure, Bill presented an alternative scenario: An “executive” device with the main product hooks up with a second, mobile device which presents the corresponding documentation. (I didn’t quite understand this point, I think Bill mentioned a second screen embedded in the primary device, but I’m not sure.)

5. Localization requirements increase

Bill sees the scope of localization expand as the need for translation no longer stops with external documentation. Increasingly, internal documents also need translations because corporations need to keep international teams afloat and cannot afford to lose traction due to vague or misunderstood communication.

This is also the reason why, economic advantages notwithstanding, machine translation hasn’t taken off yet. But a hybrid process seems promising in some areas where machine translations become useful and reliable after human editing. Enter flexibility as our audience now might also include far-flung colleagues – and our tasks might include editing text that’s been translated by robots.

6. Rethink content delivery

As we face diverse requirements for working at different speeds in more formats and for more diverse audiences, we need to be flexible and rethink what we deliver and how. With demands like these, pages of static contents are frequently not sufficient. Instead, users need more dynamic content and filters to customize the documentation to what they need at the moment.

Someone in the audience summed it up very well: “Think of content as a service, not a product.” To me that makes a lot of sense, because it emphasizes the recipient of that service and their situation over the static dead-on-arrival quality that comes with a tome of printed pages.

My summary

I think flexibility is a key ingredient in many of the trends Sarah and Bill discussed with the audience. The recent opportunity to reorganize how I create documentation has given me two kinds of confidence: I have a suitable process in place for now. And I can change processes and methods when I need to.

A secondary trend occurred to me as well: Thanks to Sarah’s spirited mc’ing by which she included the majority of audience questions and comments, this webcast felt a lot more communal than previous ones I have attended. It was almost like single-session, virtual mini-conference. And if industry leaders can bring us together outside of conference season, we can strengthen our networks and move our profession forwards – with just a little bit of flexibility.

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.