Why a content spec saves you time and money

A content specification will save you troubles, time, and money, especially when you’re not the lone writer on a documentation project. It will ensure that you offer your users consistent and holistic documentation across a team of writers.

A content specification is a list of all topics to be created which ideally maps planned topics to requirements and/or designs to ensure comprehensive and complete documentation. It usually comes in a table with one row per topic, listing:

• Topic heading and/or file name
• Topic type (concept, task, reference, or whatever else you may use)
• Topic owner
• Writer (in case writers may be different from topic owners)
• Reviewers (for example, subject-matter experts)
• Date ready for review or for post-review editing (depending on your workflow)
• Mapped deliverables (where the topic appears, for example, a certain user manual, the online help, etc.)
• Time estimate (how long will it take to write the topic, optionally, including review)
• Documentation task type, to help you estimate time:
  • Create new topic
  • Major rewrite of existing topic
  • Minor fix or addition to existing topic

Without it, you risk delivering a bunch of topics with gaps in some places and overlaps in others. You can still string them together, but no overview topic can convey a coherent content experience, if you didn’t plan for it and bake it into the topics and their structure.

So a content spec is a blueprint of your documentation project, just as you would create one before you start building a house – or design any kind of experience.

Yet content specs often elicit negative reactions…

“Oh, but we’ve managed without one so far…”

Many tech writers I know are very competent, and a few are lucky to boot. Considering all their projects with more than, say, 50 topics which didn’t use a content spec, I’d bet half of them are incoherent (“organically grown” is an oft-used euphemism).

The cost doesn’t stop at poor user experience. Such examples are also more difficult and more expensive to maintain, especially if you have overlapping topics and don’t remember to update both of them…

“Bah, reality eats specs for lunch…”

To an extent, yes. But on the whole, reality is an orderly patron. In my experience, the final documentation reflect the approved content spec in up to 80% of the topics. An average 10% of the topics get added during the writing, where concepts or prerequisite and auxiliary procedures are found missing. Another 10% of the topics get reorganized because the initial content spec misunderstood something, or because content simply makes more sense somewhere else.

“Even if, we’ll fix it later…”

Yes, you can. But once again it’s very expensive. Remember that the list of topics is only one result of the content spec. Their structure is another. Finding that a structure by workflows is inferior to a structure by, say, instrument, requires not just re-ordering topics, but re-writing a lot of them.

You can avoid this by drawing up a complete content spec before you write a single topic and getting it signed off by the key stakeholders, so they know rather well what documentation they will get. The 20% deviations mentioned above are usually justifiable, if they conceivably improve the deliverables.

– Given that content specs are a big help in creating and maintaining efficient and effective user documentation, I strongly recommend using them. If you have any experience with or without content specs, I’d love to hear it.

Advertisement

2nd day of sessions at TCUK 13

The business and managing of tech comm was the predominant topic of my TCUK13 experience, as I reflect some more on the sessions I attended and the conversations I joined.

A. Westfold on collaborative authoring in DITA

Andrew presented a case study of McAfee over several years, from separate product teams and “artisanal”  lone writers to a larger, unified team of writers collaborating in DITA. During this time, McAfee also grew by acquisitions which meant that additional writers, methods and tools came on board. Here are the most essential stages of their journey:

1. Improve several individual procedures for quick wins: Single sourcing reduced translation efforts. Automating the translation round-trip cut out costly manual layout efforts.
2. Move to topic-based authoring: They chunked up content into topics and moved them into DITA to validate the topic structure. (It turned out that many task topics could not be automated and essentially had to be rewritten in valid structure.)
3. Bring in a content management system to reap the full benefit from single sourcing and topic-based authoring. This helped to reduce the number of redundant topics and to make localization even more efficient.

While their journey is far from finished, McAfee has realized the following benefits so far:

• Easier administration of topics than of larger content chunks before. It’s also easier to solicit reviews for smaller stand-alone chunks.
• Faster, more consistent creation of deliverables for several product variants thanks to better use of standard templates.
• Documentation processes align well with recently introduced agile development processes.
• More efficient, streamlined workflow thanks to better integration between documentation and localization.

I really enjoyed Andrew’s presentation. It showed that projects to improve tech comm do work out, even if you don’t always see past the next stage, and you may have to adopt due to other changes in the company.

A. Warman on “Managing accessible mobile content”

Adrian Warman from IBM hooked up two important tech comm issues, accessibility and documentation for mobile, into a survey session.

Accessibility makes it easier for everyone to fit in, participate and contribute, irrespective of disabilities. In short, it ensures that a user’s disability does not mean a personal disadvantage. For tech comm, this means that sufficient documentation is accessible. For example, if your online help in HTML is accessible, it’s not necessary to make the same contents in PDF accessible as well – or vice versa, as the case may be. Adrian advised us to keep an eye on “EU mandate M 376” which may soon make some level of accessibility mandatory for products traded within the EU.

Mobile (smartphones and tablets) for tech comm means not just a technology, but an expectation, a mindset. It’s more than simply fitting our output onto smaller screens. Its different dimensions of interactivity, such as progressive disclosure and user-generated content, challenges us tech writers to re-think how to best convey an idea. Which is the best taxonomy that supports both, mobile devices and accessibility?

I don’t think there was a lot of new, revolutionary content here, but since I haven’t dealt much with either topic so far, it was a welcome introduction that was concise and well presented.

E. Smyda-Homa on useless assistance

Edward reported on his twitter project @uselessassist where he “Retweets to remind organizations of the frustration and negative emotions that result from poorly prepared assistance.” He presented many examples of poor user assistance. Some people complained about insufficient instructions, whether they had not enough images or only images. Some found the instructions too long (“I know how to prepare toast!”) or too short or redundant. Some pointed out typos or bad translations.

This was a very entertaining session – and you can easily get the gist of it by simply looking up the account or following the twitter feed. It’s anecdotal evidence in real-time that users actually do read the manual – or at least try to.

While every tweet is heartfelt, I think not every one merits a change in the documentation – if only because some are contradicting each other. But I find Edward’s project very enlightening and nodded to myself in embarrassed recognition a couple of times…

– Feel free to leave comments about any of the sessions, whether you have attended them or not.

Join me for “Mental models for tech comm” at STC 13

I’m proud and happy to be presenting at the STC Summit in Atlanta in a couple of weeks on meaning and mental models and how understanding them can help us in technical communication. If you’re attending the Summit, I invite you to join for me:

Addicted to meaning:
Mental models for technical communicators

Tue, May 7, 4:00 pm in room Hanover AB

My presentation will explore how “meaning” works in technical communications, why it fails and how you can create meaningful documentation. I will draw on the cognitive psychology of mental models and advances in user experience design to show why minimalism works, but FAQ’s don’t, and how to write for users without irritating them.

Being meaningful in technical communications is harder to measure than being correct, concise or consistent. However, it is just as essential: Understanding how and why communication is meaningful to users helps to create more effective documentation. Participants will get a deeper understanding and a fresh perspective on what makes communications meaningful.

You will learn:

• What distinguishes data, information, and knowledge
• How (technical) communication transmits meaning
• What mental models are and how they shape the meaning that users create from documentation
• How we are addicted to meaning
• How to ensure your documentation is meaningful

It’s a G-rated session, so you don’t need any previous experience or knowledge of psychology – just a curiosity what makes us tick when we read and write documentation.

So treat yourself to a fun romp of aha moments in the last session slot of the day – hope to see you in Atlanta!

Techcomm lessons from UXcampCPH barcamp

Two big lessons I take away from attending last week’s UXcampCPH, Copenhagen’s “un-conference” on user experience, are:

• Tech comm’ers and UX’ers can and should join forces because we have essentially the same goals.
• Barcamps can be a fantastic alternative to conventional conferences.

While the 270 attendees were a mixed bunch, to be sure, I met only about a handful of technical communicators like myself. So what was it like to be a tech comm’er among hundreds of UX professionals, graphic designers, information architects, web designers, etc.?

Barcampers hanging out between sessions at Copenhagen’s IT University; photo by @andersmn

So close, and yet so far apart

I frequently heard the question: What does a technical communicator actually do? The answer “Write documentation” proved confusing because that meant to some the documentation of a UX project. “Writing user manuals and online help” was satisfactory, but apparently not an obvious answer…

That’s a pity because at heart UX and tech comm share a gommon goals: We both make products mean something to customers. We just do it in different ways: UX’ers design the actual experience. Tech comm’ers help the user along with additional instructional, background, and technical information, when necessary.

If tech comm’s user assistance is embedded in UX’s user interface we actually blur the boundary: User assistance can start with UX field labels and progressively disclose more documentation via tool tips to a full-blown help system.

We even have an external reason to join forces as we both occasionally suffer from similar misperceptions when it comes to the value we add. The varieties of our achievements often goes unnoticed outside our respective fields, as the cliché goes: “Everyone can draw / write…” 🙂

What makes a barcamp special?

A barcamp tries to avoid many of the hierarchical pitfalls of conventional conferences. It emphasizes participation and networking over listening and consumption. The general motto is “You are the barcamp” – and the program is built at the beginning of event when potential speakers pitch their ideas for sessions. Depending on the number of votes from attendees, speakers get a spot on the program.

At UXcampCPH, everybody got to speak: Of approximately 270 participants, there were only 16 pitchers for the 24 session slots. The event was a bit special in that they invited 3 keynote speakers – which often isn’t done at barcamps to stress the egalitarian, participatory vibe. But in Copenhagen, the keynotes worked well by bringing everyone onto the same page (see my previous post of session summaries).

UXcampCPH participants pitching their sessions; photo by @JohannaBlomgren

Here’s how I would compare features:

Conferences vs. Barcamps

• Primary tool: Laptop vs. iPhone
• Communication artefact: Business cards vs. twitter handle
• Networking over drinks opportunity: Drinks reception vs. pitchers of beer
• Food: Banquet buffet vs. organic soup kitchen
• Location: Conference hotel/convention center vs. university lecture halls
• Sponsors’ presence: Trade exhibition vs. brand exposure via room names & swag

If you know more reasons why tech comm and UX should join forces – or what distinguishes barcamps from conferences – feel free to leave a comment!

Half-price sale ebooks on UX and tech comm

O’Reilly sells ebooks from the publishing group Elsevier at half price until 23 April.

I blog about it because I think this is a good deal. Also, I like O’Reilly ebooks because they are DRM-free. I am not affiliated with O’Reilly or Elsevier. I get no payment in money or in kind for writing this.

Here are some titles of interest for tech comm and UX people. So if you’ve heard about one of these titles or keep it on a list of books to check out, here’s a good opportunity.

• The info below is straight from the O’Reilly web site.
• Prices are before the discount.
• Use discount code WKESEVE to get 50% off until 23 April.

For tech comm

Designing the Search Experience
By Tony Russell-Rose, Tyler Tate
December 2012
Ebook: $39.95

Letting Go of the Words, 2nd Edition
By Janice Redish
September 2012
Ebook: $49.95

Information Visualization, 3rd Edition
By Colin Ware
May 2012
Ebook: $64.95

Content Strategy at Work
By Margot Bloomstein
January 2012
Ebook: $29.95

For UX

Designing the Search Experience
By Tony Russell-Rose, Tyler Tate
December 2012
Ebook: $39.95

Agile User Experience Design
By Diana Brown
October 2012
Ebook: $39.95

Observing the User Experience, 2nd Edition
By Mike Kuniavsky, Andrea Moed, Elizabeth Goodman
September 2012
Ebook: $59.95

Information Visualization, 3rd Edition
By Colin Ware
May 2012
Ebook: $64.95

Quantifying the User Experience
By Jeff Sauro, James R Lewis
March 2012
Ebook: $49.95

Sketching User Experiences: The Workbook
By Saul Greenberg, Sheelagh Carpendale, Nicolai Marquardt, Bill Buxton
November 2011
Ebook: $19.95

Global UX
By Whitney Quesenbery, Daniel Szuc
October 2011
Ebook: $49.95

User Experience Management
By Arnie Lund
May 2011
Ebook: $39.95

Brave NUI World
By Daniel Wigdor, Dennis Wixon
April 2011
Ebook: $39.95

Thoughts on Interaction Design, 2nd Edition
By Jon Kolko
January 2011
Ebook: $29.95

Usability Testing Essentials
By Carol M. Barnum
October 2010
Ebook: $49.95

Smart Things: Ubiquitous Computing User Experience Design
By Mike Kuniavsky
September 2010
Ebook: $41.95

Sketching User Experiences: Getting the Design Right and the Right Design
By Bill Buxton
July 2010
Ebook: $49.95

Measuring the User Experience
By Thomas Tullis, William Albert
July 2010
Ebook: $53.95

Visual Thinking
By Colin Ware
July 2010
Ebook: $45.95

User-Centered Design Stories
By Carol Righi, Janice James
July 2010
Ebook: $69.95

The Essential Persona Lifecycle: Your Guide to Building and Using Personas
By Tamara Adlin, John Pruitt
March 2010
Ebook: $31.95

UXcampCPH sessions summarized

I attended UXcampCPH, a barcamp-type conference on user experience (UX) design in Copenhagen, last weekend. It was great! There were about 270 people from different countries and different professions, but all of them passionate about UX and willing to share what they knew in sessions and discussions.

Huge thanks to the local organizers who were incredibly dedicated and competent all through the event and pulled it off without a hitch! And thanks to the sponsors who made this all possible.

Below is a summary of some of the sessions I attended. I’ll have more to say about what tech comm can learn from UX and the differences between the two professions and between a barcamp and a conference, so watch this space. (There’s RSS and e-mail subscriptions to the right to remind you when new posts appear…)

Navigation as cross-channel sense-making

Andrea Resmini‘s keynote on Friday was a dense conceptual talk about navigation. Whether on a web site, in an app or in a city, navigation helps use to make sense of our surroundings. We use paths, of edges/walls and of nodes/intersections to choose from available options.

Andrea Resmini starting his keynote, being photographed by Eric Reiss; photo by @kmdk

In our navigation, our perceptions may differ from the physical reality as a city map never matches our personal idea of a city. But maps still are good, sharable representations of quests in which we act our personal narratives.

On the web and in apps this means that we need to learn to “navigate the database”, for example, by perceiving Facebook as our regular bar: It’s probably not a perfect place, but it’s where all our friends hang out. So as we use navigation, we create our own choreography across several channels which makes our experience cohesive and meaningful.

– I thought Andrea’s talk was a bit academic, but certainly thought-provoking. I was glad that a friend of mine had previously tipped me off to one of his earlier talks about “Pervasive IA” which I found a bit more pragmatic and a good introduction to Andrea’s work.

Prototyping user experience

Leisa Reichelt‘s opening keynote was a well-argued, convincing plea for prototyping. Iterative prototyping beats waterfall projects – if you can afford it.

Waterfall-model projects, Leisa said, are often more orderly than the projects and the real world which hosts them: They “require your best ideas while you still know least about the problem.” But if you start out the project with an assigned front-end developer and real content, you can start with a good idea and iterate your solution until it works in terms of quality and volume and until it satisfies the customer (or time/money run out).

Photo by @Berlinertorte

Prototyping, according to Leisa, beats abstraction, will expose stupid ideas quickly and helps to make good decisions based on real content and real solutions. It makes the strategy live in deliverables, not in meetings.

There are two potential issues with prototyping:

• Some companies find it more difficult or more expensive to throw away a prototype development than a solution design. But in either case you will most likely throw away something during a project.

• It’s an artisan model that doesn’t scale well: It’s great in one project, but it’s very difficult to assign the same developer or designer or technical communicator to two projects at the same time.

– I enjoyed Leisa’s talk thanks to her way of presenting: Very lively, emphasizing stories and anecdotes, but her main points are well supported by her slides. It inspired me enough that I will try prototyping in the near future – I have a small in-house tech comm project for which this might work well… 🙂

Pattern recognition

In my own session, I talked about pattern recognition as an essential mental strategy for acquiring and disseminating knowledge, even though most of us are not aware of it. When applied consciously, UX designers can employ pattern recognition processes to develop effective user experiences more efficiently and help users orient themselves.

– I sincerely thank the 100 or so people who attended my session for their kind, attentive reception. I am especially grateful for the engaged discussion we’ve had how pattern recognition can be applied to UX design. You can find my slides over at slideshare.

Simple drawings

Louise Klinker in her presentation showed the many ways how just about everyone can use sketching. First, she walked us through the basics how most people can draw basic shapes like a line, a circle, a rectangle, a triangle, a wavy line and a 5-pointed star. Then she showed how you don’t really need any more shapes than these. Put them together, and you can sketch people (a 5-pointed star with a circle instead of the top arm), place (houses or meadows) and process (using arrows, clouds, symbols).

Second, she showed that sketching can be useful in many areas of business. You can, of course, sketch the obvious, such as GUI and web site designs, but you can also sketch plans and workflows. You can sketch processes and agreements and from them whole business models. Here’s the basic business model of AirBnB:

Photo by @isa_157

– I’m habitually very much a words guy (hey, I’m called a tech writer, not a tech sketcher…). So I really enjoyed that session, because it got me over the fear of sketching and the thought that I cannot draw… I’m nowhere near the 30 days or so it takes to anchor a new habit, but I’m not such an “un-drawing” guy as I thought…

Expert reviews

Rolf Mölich showed how expert reviews of web sites are as reliable as and not more expensive than usability tests with users – IF they are done right. Because data trumps opinion any time.

Photo by @saevarsson

To get expert reviews right, you need actual experts in both usability and the subject domain, these experts need solid methods, and the test needs open discussion to avoid dismissal of the experts’ results as mere opinions.

– I liked Rolf’s interactive mode that had us signal our collective opinions about expert reviews using green, red and yellow (the latter for undecided). And I appreciated his candor when he admitted that he’d had second thoughts about the heuristic method he invented with Jakob Nielsen about 20 years ago.

Beyond responsiveness

Eric Reiss‘ closing keynote summed up many threads and ideas of the day, among them:

• Anticipatory design can improve upon responsiveness. Responsive design often focuses on the device more than on the user. For anticipatory design, extract patterns of use and behavior and make the application situationally aware. The situation includes not just location, but also time of day: Around midnight, show me the bars close by, not the barbers.
• More isn’t better. A portal with 49 links and zero focus is not useful. 20 pages with a good story beat a thousand pages.
• Big data, bigger insights. Spot patterns in user data and decide which are meaningful and relevant to your user experience to derive value.

Photo by @mortenriis

• Create uniqueness. The “A” in IA (information architecture) is not only about structure and usefulness, but also about having a personality and beauty. Don’t worship form: Design patterns are mere templates, not design in itself. Don’t enslave yourself to the process.

– Eric brought the barcamp to a great close with his lively presentation. I didn’t mind much that it was a collection of points rather than a coherent narrative, because I could recognize and connect to several of them as he summarized the last one and a half days.

If you’ve attended one of the sessions, feel free to leave a comment or question!