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?

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.”

Address information overload in tech comm

Addressing information overload helps your user assistance succeed when knowing your audience and offering correct and concise content is not enough. You can have great topics well-written and well-structured, if they’re part of an information deluge, they won’t help your users get their stuff done.

I take my cue from a post by Nathaniel Davis over at UX matters called “IA Strategy: Addressing the Signatures of Information Overload“. Nathaniel describes six such signatures. I think at least three of them have something to say why and how too much information fails in documentation, too.

1. Feedback

Feedback is the essential reality check to determine whether users suffer from information overload. Customers may report that they’re not sure they’ve found the right information or they cannot apply it efficiently. Even if the content is fine topic by topic, the bulk of information is unmanageable. In this case, consider improving search and browsability for more efficient use of the documentation.

2. The utility gap

The utility gap means that customers only use a small fraction of all the information they have at their disposal. As Nathaniel says, it’s what I have vs. what I use.

If certain user types experience utility gaps, consider addressing them with special documents. For example, you could assist novice users with a quick start document. Or address a special use case which only requires one of the many processes, plus some reference information. With topic-based authoring, it’s usually easy to create such additional documents by re-using the relevant topics. (Maybe add one or two specific “glue topics” to make sure the new document still flows nicely…)

If all users experience utility gaps, consider progressive disclosure by layering your content. The benefit of offering all content within three mouse-clicks wears off if it’s too much. Progressive disclosure structures content by providing the most essential, most frequently used topics first and more obscure information later. Make sure, however, that all topics remain searchable and findable!

3. Filter failure

Filter failure means that users lack ways to judge which information to trust and use. It’s what I can use vs. what I should use. Filter failure can be solved with tools and with content.

Customers who are confident to use their own judgment require tools to filter information. In documentation, faceted search allows users to reduce search results by categories to weed out inapplicable information.

Customers who prefer to rely on expert judgement will benefit from recommendations in the content itself. Consider adding such recommendations for certain user roles or use cases to guide customers to the most suitable information.

- Have you had symptoms of information overload in documentation? Would these strategies help users to cope? What other solutions are there? Feel free to leave a comment.

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.

tekom Danmark is off to a good start!

tekom Danmark, the Danish country group of Europe’s tech comm association, is off to a good start, thanks to good attendance and enthusiasm during the foundation event in Odense on 5 November.

The afternoon combined official speeches with two presentations about topic-based authoring, each followed by a lively discussion. A get-together over dinner concluded the event in high spirits (and I don’t mean alcohol).

What does tekom Danmark do?

At 15:30, Per Sørensen, head of the Initiative Committee for tekom Danmark, kicked off the event that brought together around 40 technical communicators who represented a wide variety of industries and services from all across Denmark.

Michael Fritz, CEO of tekom (the German association), presented what tekom is and what it does. Denmark is not the first country group – there are already country groups in Switzerland, Italy, Romania and Turkey.

Holger Thater, a German tekom member based in Hamburg, will act as mentor to tekom Danmark. He explained specifically what tekom Danmark will be all about:

• The general mission is what you would expect from a professional association: To provide networking opportunities, to facilitate exchange of knowledge, to offer training and qualification and to generally raise the profile of the profession.
• To ensure that a tekom country group has a chance to succeed, it takes the explicit support of 10 tekom members in that country and a so-called initiative committee who works with tekom to found the country group and get it up and running.
• tekom supports country groups by assigning a full-time employee who is the official liaison to tekom (Germany) and a country mentor who offers guidance and, let’s say: spiritual support.
• tekom also offers a nascent country group an organizational framework of a start-up timeline and some budget with which to offer 4 events per year that are open to tekom country group members.
• Interested parties are welcome to attend the events and can become a country group member for free during the first year.

After laying out the framework and procedures, Michael Fritz officially founded tekom Danmark.

Presentations and discussions

After a short break, I had the honor and pleasure to present one of the two sessions. I spoke about features and benefits of task orientation and topic-based authoring. As it turned out, aproximately half of the attendees actually use topic-based authoring, so I refocused my presentation.

Rather than going to great lengths about what topics are and how they work, I emphasised how the company I work for uses a DITA-derived information model to write topics. My presentation segued into a lively discussion about technical opportunities which our structure and our tools offer. Strategic opportunities and limitations also came up. I was glad to offer attendees a glimpse at processes and tools that work for us, and I’m happy to see that the comparison was engaging and enlightening to many.

Bo Brandt, a self-employed technical communications consultant, shared a case study where he accompanied a project from unstructured FrameMaker to Topic-based authoring with Arbortext. It was a perfect complement: His project emphasised translation more than our situation, and he had several interesting lessons and pitfalls to share. The tireless audience engaged Bo in questions about his strategy, tactics and tools.

A little before 19:00, we gathered for a group photograph, dinner and drinks. (Okay, so a little alcohol…)

What’s next?

Personally, I’m already looking forward to the next actions of tekom Danmark! Since I’m working for a Danish software company, tekom Danmark is almost like homecoming to a place I didn’t have until now.

A next event is not yet scheduled, but the idea is to move around Denmark, so look for events in København, Aalborg, Århus or the like. To keep us busy until the next event, we have already formed a tekom Danmark LinkedIn group which is moderated, but easy to join.

If you’re a technical communicator working in Denmark or if you are working with technical communicators in Denmark, I highly recommend that you join the LinkedIn group and check out tekom Danmark. It’s been great to spend an afternoon with such a diverse group of enthusiatic colleagues, and I think we’ve seen the beginning of a fruitful network!

Denmark gets a tech comm association again

tekom Danmark, the country chapter of Europe’s largest tech comm association tekom, will be founded on 5 November in Odense. If you are a technical communicator in Denmark – or even West-Sweden -, consider joining us for the public inaugural event. And even if you cannot make it on that day, join the tekom Danmark LinkedIn group to connect with other Danish tech comm’ers and keep up with association news.

Click to open invitation in PDF

I met Per Harbo Sørensen, Head of the Initiative Committee for tekom Danmark, at tekom last week. He told me that there is considerable interest in having a professional association in Denmark again, after the regional STC chapter folded several years ago.

tekom Danmark provides opportunities for networking and exchanging opinions and tips and tricks how global trends in technical communications affect professionals locally.

For technical communicators seeking professional recognition, tekom Danmark offers access to TC TrainNet, an international training and certification program for technical communication.

Agenda

The day’s agenda is a good mix of formal speeches, professional presentations and networking opportunities. So it should give everyone a good idea what tekom Danmark will be all about. For all the details, open the invitation in PDF.

Founding tekom Danmark
15:30 Welcome
15:40 Introduction to tekom (mission, tasks and goals)
16:10 Introduction to tekom Danmark
16:30 Formal foundation of tekom Danmark

Topic-Based Authoring (professional presentations)
16:45 Features and Benefits of Task Orientation and Topic-Based Authoring
17:25 From Unstructured FrameMaker to Topic-Based Authoring with Arbortext
18:00 Open discussion

Networking
18:30 Buffet

Event details

tekom Danmark Foundation Event

Monday, 5 November 2012, 15:30–18:30

Odin Havnepark
Lumbyvej 11
5000 Odense C
Room 1.13

- As a tech communicator who’s working for a Danish company and involved with tekom, I’m very excited to be part of this event! See you there!

Top 4 steps from manuals to topics

A little bit of planning ensures you get clean, manageable topics from your conversion of user manuals.

While most help authoring tools support importing Word documents, there’s more to getting re-usable topics out of user manuals, as I’ve found out. I’ve spent the last few weeks converting 3 related Word manuals of 360 pages into 400 topics in Madcap Flare – though I believe that the process below applies to other tools as well.

The aim was to merge the contents from separate Word-to-PDF manuals with the online help topics into a single sourcing repository from which we can create both online help and manuals.

My two key lessons of the conversion are:

• Plan first, execute second – several hundred topics are too many for trial & error and picking up the pieces later.
• Do each task as early as possible – some Word idiosyncrasies are hard to clean up after the conversion.

And here’s how I did it in 4 steps:

 

1. Start with plans

The whole conversion exercise benefitted much from a couple of designs that I followed:

• An information model
• A folder structure for my topics

The information model defines the 4 topic types we have and what each type contains internally. It’s basically “DITA, without the boring parts” about which I blogged previously.

The folder structure divides my one Flare project into several sub-folders, so I don’t have 400 topics in one heap. Instead, I now have 13 sub-folders which divide up my topics by topic type (concept, task or reference) and even by task type (initial setup or daily workflow). That makes it easier to manage the topic files.

2. Prepare for the import

Once I had the basic structure to organize topics and their insides, I prepared my Word manuals, so I didn’t have to deal with a GIGO situation, where I get Garbage In, Garbage Out.

First, I edited the documents into topics, so each section could become either a concept, task or reference topic – or an auxiliary topic which ensures that the chunks still flow nicely when you read them in the future manual output. I also ensured that section headings indicate topic contents and type:

• Concept topics use noun phrases as headings
• Task topics start with an imperative

Then, I cleaned up the documents. You can convert unstructured Word with layout applied in styles, modified styles and manual formatting into topics just fine, but it will give you unmanageable content and endless grief. So do your future self a favor and dissolve all modified styles and manual formatting.

3. Import

Thus prepared, I’ve found that Flare’s built-in Word import is very good, consistent and reliable if you throw well-structured Word documents at it. Only tables didn’t import well (or I couldn’t figure out how to do it), so I re-styled them in Flare.

If you’re a stickler for clean topics, you can go ahead in Flare and clean out unnecessary remnants:

• Remove Word’s reference tags in cross references by replacing *.htm#_Ref1234567″ with *.htm”
• Remove Word’s Toc tags in Flare’s table of contents by replacing *.htm#_Toc1234567″ with *.htm”
• Remove Word’s Toc anchors in topics by deleting <a name=”_Toc*”></a>

4. Adding value to topics

At this point, I had a pile of 400 clean topics, but no added value from the conversion yet. That came from additional tasks:

• Dividing up topic files into the folder structure, which makes hundreds of topic files manageable.
• Assigning a topic type to topic files (Flare lets you do that for several files at once, so this was very fast), which makes the content intelligent, because topics “know” what they are.
• Assigning in-topic elements (as div tags) to topic paragraphs according to the information model, which allows you to identify and reuse even parts of topics, for example, instruction sections or example sections.
• Creating relationship tables for cross-references into relationship tables where feasible, which ensures that links are easier to manage and to keep up to date.

Your turn

Have you done a similar conversion? What were your experiences? Did you do it yourself or with an outside consultant? Feel free to leave a comment.

DITA with confidence (DITA Best Practices book review)

I recommend DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA by Laura Bellamy, Michelle Carey, and Jenifer Schlotfeldt to anyone who looks for practical guidance with DITA or topic-based writing with a future DITA option. (This book review has appeared in the Summer 2012 issue of ISTC’s Communicator magazine on p. 57 in different format.)

The DITA bookshelf has been growing slowly but surely. Thanks to the recent addition of the seminal DITA Best Practices, you can now find most information you need for a DITA implementation project in one book or the other.

The paperback comes from IBM Press which has also given technical writers Developing Quality Technical Information by Gretchen Hargis, et al. If you know that recommended title, you will enjoy the same usefulness and clear layout in this new book.

Starting with topics

DITA Best Practices addresses the practical concerns of writers, editors and architects of DITA content in three well-structured parts. The first part on writing starts with a chapter on topic-based writing and task orientation as two methods underlying DITA. The authors give clear instructions and guidelines for both methods. A generous amount of tips, best practices and ‘watch out’ warnings add the voice of the experienced practitioner which help to keep you on track or avoid beginner’s mistakes. The fictional ‘Exprezzoh 9000N’ coffeemaker is used consistently throughout the book to illustrate tasks and topics. Explanations why and how the methods work give writers the motivation to apply the advice with confidence. The chapter ends with a concise wrap-up section of the big points and a checklist to ensure you apply these big points in your work.

I have outlined the first chapter in such detail, because its clear and competent combination of elements — instructions, tips and warnings, examples, motivation, wrap-up and checklists — make this book so useful throughout.

One chapter each is then dedicated to topic types task, concept and reference. Each chapter describes the characteristics and motivation for the topic type, followed by instructions and examples along the standard DITA topic structure. The task chapter, for example, proceeds from <title> via <shortdesc>, <context>, <prereq> to <steps>, etc. However, most guidelines, examples, tips and warnings apply to good topic-based writing practices in general.

A chapter dedicated to DITA’s ‘short description’ element with its multiple uses in topics, links and search results helps novices with the challenge to use this powerful element correctly.

DITA’s architecture explained

The second part of the book builds on the first. After describing topics as DITA’s most essential building blocks, the book focuses on making topics work together by connecting them and by expanding their usability.

Two chapters show you how to connect topics into a coherent output, such as an online help system or a book. The first chapter on DITA maps explains how to create tables of contents, including bookmaps for print publications. The second chapter on links describes the four different ways to link topics to each other that in DITA. In their reassuring style, the authors help you to distinguish them, so you understand when to use which link type and how to apply each correctly.

The next three chapters explain how to make topics work together by expanding their usability: You can use metadata to make your topics ‘smart’ by adding information such as index terms, addressed audience or described product or version. You can use conditional processing to customise output. And you can reuse content for more consistent output and reduced translation costs. A clear workflow helps you to determine which of your content you can reuse and how.

Editing in DITA

The third part of the book deals with editing. One chapter outlines the steps and decisions of a project to convert your exiting content to DITA. Useful worksheets help you to analyse your content and prepare it for conversion. The chapter on code review helps you to avoid or eliminate common problems that restrict the benefit of your DITA code. Based on their experience, the authors remind you to use DITA topic types and elements correctly, for example, to use the <steps> element in task topics instead of a more generic ordered list. The chapter on content editing applies best practices of editing to DITA topics and maps.

Useful and recommended

Since it came out, I have used this book more than any other technical writing book, except a style guide. Had it been published earlier, it would have saved me many an uncertain moment when I was designing and teaching our information model. I especially appreciate the clarity, the concision and the well-argued advice of do’s and don’ts. For all its benefits, be aware that the book covers neither the DITA Open Toolkit nor DITA specialisations!

DITA Best Practices lives up to its subtitle and provides essential instruction and advice to technical writers, editors and information architects. Project managers will find it equally helpful but should also consider Julio Vazquez’ Practical DITA which reflects a project structure better. Decision-making managers are probably better off with Ann Rockley’s DITA 101 which gives a shorter high-level overview.

A. Ames & A. Riley on info experience models at STC12

Andrea Ames and Alyson Riley, both from IBM, presented a dense whirlwind tour on “Modelling Information Experiences” that combine four related models into a heavy-duty, corporate information architecture (IA).

While the proceedings don’t include a paper on this session, Andrea posted the slides, and the presenters published a related article (login required) “Helping Us Think: The Role of Abstract, Conceptual Models in Strategic Information Architecture” in the January 2012 issue of the STC’s intercom journal.

The session proceeded in six parts. First, Alison explained IA models in general and how they work. Then Andrea described each of the four model types that make up an IA specifically.

IA models as science and art

Information architecture relates to science as its models draw on insights and theories of cognition. And its models relate to art as they aim to create a meaningful experience. Both aspects are important. Only if IA models manage to blend science and art can they touch the head and the heart.

The session focuses on IA models instead of theories (which are too vague and abstract) or implementations (which are too specific and limited). Thanks to the in-between position of IA models, we can use them to

• Ask the right questions to arrive at a suitable, feasible IA
• Tolerate the ambiguities of “real life”

Models present descriptive patterns, not prescriptive rules. They don’t say how stuff must be, but how it can be represented. They differ from real life, but real life is still recognizable in them.

That means you cannot simply implement a model on autopilot and get it right. Instead, you have to

• Think how to implement the model
• Vary the model for your users’ benefit
• Listen to the right knowledgeable people when implementing

Models help you think

To arrive at your concrete IA, you take the model’s abstract patterns and apply your project-specific details to them, the who, what, where and when.

This task is less mechanical and less copy-and-paste than it sounds. It’s not so much a question of following rules and recipes, but of making abstract patterns come to life in a coherent, flexible whole. (If you’ve ever tried to create meaningful concept or task topics by following an information model, you know it’s more than just filling in a DITA template. You need to use your own judgment about what goes where to achieve and maximize user benefit.)

Since there are four related models, you need to think carefully how each of these models should benefit your users. And the models help you think, they scale and adapt to:

• How your business and its information requirements develop over time, how they grow and expand in desired directions
• How your customers find, understand and apply the information they need

The four IA model types

The IA model that Andrea then explained consists of four related model types:

use model (content model + access model = information model)

Each of these model types needs to be developed and validated separately.

The use model defines how users interact with information. It describes standard scenarios for optimal user experience within the product or system context. It outlines what information users need and why and how they use it. It includes use scenarios for the entire product life cycle and user personas that outline different types of users. Fortunately for us technical communicators, Andrea pointed out, describing all this is part of our core skill set.

The content model defines how information is structured effectively. This could be DITA (in the case of the company I work for, this is what we call our DITA-derived “information model”). It includes the granular information units and their internal structure, for example, task topics and their standard sequence of contained information. It also describes how these granular units are combined into deliverables.

The access model defines how users access the information efficiently. It makes provided information useable, thanks to a navigation tree, a search function, a filtering function to increase the relevance of search results, an index, etc. Artefacts of this model type are wireframes, storyboards, a navigation tree and the like.

The information model defines how users get from one stage to the next. It uses the other three model types as input and fills in the gaps. It combines the content and access models which probably work fine during the installation and configuration processes, but may not yet carry a user persona from one stage to the next. As such, the information model is sort of the auxiliary topic that you sometimes need to insert between concept, task and reference topics to make a complete book out of them. At the same time, this model type is more detailed than the use model and closer to the other two types.

My takeaways

I was extremely grateful for this session and rank it among the top 3 I’ve seen at the summit – or any tech comm conference I’ve been to! Yes, it was fairly abstract and ran too long – my only complaint is that it left only 2 minutes for discussion at the end.

As abstract as much of the session was, it actually solved a couple of problems I couldn’t quite put into words. After designing and teaching our company’s DITA-derived information model (which is a “content model” by this session’s names), I thought our model was applicable and useful, but it had two problems:

• Our model lacked context. – Now I know that’s because we haven’t mapped out our use model in the same detail and failed to connect the two.
• Our model was baked into a template for less experienced writers to fill in – with varying results. – Now I know that’s because the models are not supposed to provide templates, but require writers to use their own judgment and keep in mind the big picture to deliver effective information.

Another lesson I learned is that many structured information paradigms seem to include a less rigid element that sweeps up much of the miscellaneous remnants. In DITA, there’s the general topic which is used for “under-defined” auxiliary topics to give structure, especially to print deliverables such as manuals. In this IA model, there’s the information model which fills the gaps and ensures a more seamless user experience than the other three models can ensure.

- For an alternative take, see Sarah Maddox’ post about this session.