Sarah Maddox's Blog, page 25

The Making of “The Language of Content Strategy” (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

The Language of Content Strategy is a book by Scott Abel and Rahel Anne Bailie. In this session at STC Summit 2014, Scott Abel discussed the content strategy, tools and technologies behind the making of the book.

Problem statement

Time, money, skills and experience are in short supply. Hand-crafting content is expensive, time consuming and not scalable.

The demands of the audience are changing. People use social media, rather than going to a specific website to gather information.

To meet the demands of content delivery today, we need to adopt manufacturing principles. The is made possible by content engineering: The application of engineering discipline to the design and delivery of content.

Case study: The making of  The Language of Content Strategy

In this session, Scott will show us how he and Rahel created a book, an eBook, a website, and a set of learning materials, from a single source, without breaking the bank. They did it by harnessing technology and crowd sourcing.

Scott talked about the differences in approach between technologists and editorialists. Conflict and time wasting arise because of a lack of a common language. Rahel and Scott wanted to craft a solution: A crowd-sourced book about content strategy that is both a case study in content engineering and a practical example of content marketing.

Setting up

The team started with careful analysis of the educational landscape, contributors, and more. Then they defined the content types they needed.

The smallest unit of content they would create would be a term and definition pair.
Another content type is an essay of 250 words.
Then there are contributor bios, statements of importance, and resources.

For the authoring environment, the team selected Atlassian Confluence. It’s a wiki with support for XML content re-use.

They also chose a gimmick: 52. The project included 52 terms, 52 definitions, by 52 experts, published over 52 weeks, and one of the output formats was 52 cards.

Then they selected a team of experts: the best and brightest in tangentially-related fields.

Other roles and responsibilities: markup specialist, editor, indexer, peer reviewers, and a graphic artist.

The source data

The source was authored in Confluence wiki. The content types are clearly labelled: Biography, importance statement, topic name, definition, etc.

The output

In the various output formats, the content is structured differently but still consists of the various topic types. For example, in the printed book every chapter is two pages long, and consistently structured. The eBook format is slightly different, as are the website format and the flash cards learning format.

Each Thursday, one chapter is automatically published. The web output also contains audio files, photos, and additional resources that are not contained in the book.

The advantages of a future-proofed content strategy

The team was able to add content after the fact, such as the audio files for accessibility. The content strategy was designed to future proof the content, so the team was able to adjust to challenges and opportunities. And the strategy is repeatable. Now that it’s been done, it can be done again.

Scott told an amusing story of how he disobeyed his own rules, and tried to create another channel by copying and pasting instead of using the single-sourced content. A marketing person asked him to create a slide deck from the content. He was on a plane, without WiFi, so decided to do it by cutting and pasting. Needless to say, this didn’t work. By the end of the flight he had only 13 slides of the required 52, and had run out of laptop battery!

Cost

The cost of the project came in at under $10,000USD.

Approximately $4000USD forgraphic design, indexing, editing, markup assistance, audio tracks and hosting, the URL for the first year, and site hosting for a year.
Approximately $5,440 for book donations, postage, Adobe InDesign, Confluence Wiki, and overhead/administrative costs.

Scott’s promise

Scott finished by saying that if you want to undertake a similar project, ask him. He will try to help.

This was a fun and inspiring talk. Thanks Scott!

Information Architecture Bottom Up (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

Mark Baker, author of the book Every Page is Page One, presented a session on Information Architecture Bottom Up. The outline of his talk ends with this summary:

This session will look a practical examples of top-down and bottom-up information architecture and will illustrate where top-down fails, and how to create a bottom-up architecture to replace or to supplement your top-down approach.

Bottom up

Traditionally, information architecture organises knowledge from the top down. As examples, Mark showed us the Map of the System of all Human Knowledge from the Encyclopedia of Diderot & d’Alembert, the Linnaean classification system, and the Dewey Decimal system.

One of the simplest forms is the table of contents. You start with a general concept, and then drill down to the details. Such classifications tend to end with a category of “miscellaneous” items.

Sometimes tables of contents even act as a classification scheme, such as a clickable classification of organisms.

Another form is a system which lets you find out what medical problem you have, by progressively narrowing down your symptoms.

Mark showed us other examples of hierarchical organisation of data. Then he showed how hierarchies don’t necessarily meet a user’s needs. For example, if you’re looking for a convertible car, and the information on a car sales site is organised by year/transmission/price… and eventually by body type, you’ll need to move up and down the hierarchy a lot before you find what you want.

We will never find the hierarchy that will suit all users’ needs, because people have different needs.

Faceted classification

Such systems let you choose the things that are important to you. For example, a car sales site may have a set of various selection criteria in a side panel, such as price, transmission, mileage, year. You can choose to fill in some selection criteria and not others, and so find what you need.

There’s a big technological difference here. Paper can’t provide faceted classification, but computers can.

This is still top down. It’s a collection of taxonomies that define the things people are interested in, with respect to buying cars. It works, because most people buying cars know this particular taxonomy. But it won’t help people who don’t know the taxonomy. There are still classification problems.

Experts classify, the rest of us name things

A nice quotation from Mark:

“Experts classify. Everyone else names.”

Looking at flowers, and pansies in particular, the scientific classification of a pansy isn’t particularly useful to most of us. Looking at a Google search for common names of pansies:

Searching for “stepmother flower”, you find plenty of information and images for pansies. That’s good. In such cases, a search engine like Google works.
Searching for “football flower” shows images of pansies, and also of footballs made of flowers. Some good, some potentially confusing.
Searching for “Three faces under a hood” is particularly interesting says Mark. Looking at the images, you see a pansy (good), a girl in a hood, two people under the hood of a car, and a composite photograph showing the three faces of Mt Hood.

Scalability

None of the classification systems scale well. Tables of contents can get immensely long. Mark showed some examples from a book and an online help system.

There’s often too much variety, which leads to complexity and unevenness

Mark quoted David Weinberger: “Everything is miscellaneous”.

Everything flows to the Web

We shouldn’t attempt to push content into channels. Reuse is a big subject, often for the sake of being able to deliver the same content to multiple channels.

Problem, says Mark! There are no channels any more. All content flows to the web.

If people search for something on the Web, they will find the most popular hit – which will probably be your most popular product, even if published a few years ago.

Moving towards bottom up

What happens when someone does a search and ends up on a page in your content? They don’t start at the top. They start on the page that Google sends them to.

Mark isn’t saying we should throw away all the top down architecture. But we do need to start adding bottom up information architecture to our content.

Subject affinity

Looking at Wikipedia: it’s highly organised. There are various links and ways to move around. But it’s not ordered. Organised, yes. Ordered, no. The links point to related information, which provides a type of semantic clustering.

Dynamic semantic clustering

Mark showed us examples of information clusters that are dynamically organised:

Twitter hash tags
RSS feeds
Forums. Sometimes these are organised by number of votes.

Linking interesting connections without making a bowl of spaghetti

Most of the problems that people find are the irregular associations, and multiple connections. If things are regularly organised, people don’t usually have problems. So we need to help people with the irregular associations.

In a bottom up architecture, it’s easy to link to the interesting associations. If you tried to map all these associations from the top down, you’d soon have an incomprehensible bowl of spaghetti. In a bottom up architecture, the links show connections that are relevant in this context.

“A topic in a bottom up architecture is a hub of its local subject space.”

How do you make sure people don’t get lost?

This was a question from the audience. Marks’ answer was that you have to design the content for a bottom up architecture. You can’t just take the content from a top down hierarchy and put it into a bottom up system.

You must build context into the subject matter. Context in the table of contents doesn’t matter, but context within the subject matter does. Every page is page one, so every page must start by establishing the context. “Where am I.”

How can you filter the links based on the reader’s context?

In a tech comm point of view, you must have a systematic design for linking. A taxonomy is vital here. So, a taxonomy is not used for generating a table of contents, but instead for organising your links.

What about procedures and workflows?

What if a sequence must be performed in order? Mark’s answer is that a procedure should be the subject of a single topic. In top down design, a table of contents should not express a workflow, although it often does. So, workflow is one of the most important use cases for a bottom up architecture.

A person from the audience mentioned that you can illustrate workflow via a progress bar or images illustrating steps, which can link to steps in a complex workflow.

Topic types

Due to lively discussion with the audience throughout the presentation we ran out of time a bit, so Mark ran quickly through the types of topics in a bottom up architecture:

Workflow topics. We mentioned these above.
Pathfinder topics. These are about how you get from a business topic to an action in the system.
Big picture topics.
Tasks.

Walled garden or bazaar

Mark finished by comparing the top down approach (a walled garden) to the bottom up approach (a bazaar). The main difference: in the pictures Mark showed us, the bazaar had people in it. :)

Thanks Mark

It was a pleasure and a privilege to hear you speak.

Minimalism (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

Barbara Beresford‘s session was entitled “Minimalism—It’s Really About the User!” Here is an extract from Barbara’s summary of her session on Lanyrd:

Minimalism is a widely accepted and influential methodology in technical communications, but it is not a simple method to understand or apply. John M. Carroll’s two books on minimalism: The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skills (1990) and Minimalism Beyond the Nurnberg Funnel (1998), provide the best source for the ideas behind the theory.

Minimalism begins with understanding your users—in particular, how they need to use your software in order to accomplish their specific business goals. Designing content that really addresses this problem is notably more difficult than simply documenting the features of your software. But tackling this problem can help you develop much more usable content!

Introducing minimalism

“Minimalism” – It’s seemingly a simple word, says Barbara, but it’s surprisingly difficult to get your head around it.

Barbara talked about her path to minimalism. She says she has some “special expertise as an impatient user”, which gives her a special insight into minimalism. This got a laugh of recognition from the audience. She also gave us a useful list of references to books, articles and methodologies that have influenced minimalism. These include DITA, content strategy, Information Mapping, Every Page is Page One by Mark Baker, and more.

Minimalism is a theory of learning developed by John Carroll at IBM in the 1980s. He used the term the Nurnberg Funnel to describe the way people learn. They’re not passive when learning. They want to drive their learning experience, based on what they already know and what they want to achieve.

His study found that when people are handed a comprehensive set of instructions, only approximately 1 out of 20 follow the instructions from beginning to end. The others jump around, do their own thing, make mistakes, get lost, and have trouble finding their way back. People like to do things their own way.

In response, Carroll decided to design tutorials that start users immediately on meaningful and realistic tasks – things they needed to do. He also wanted to reduce the amount of content, and make errors and error recovery less traumatic.

So instead of comprehensive coverage, he aimed for selective coverage based on the user’s goals.

Barbara used the terms “minimalist design” and “systems design” to compare the two approaches. (At first I was not quite sure why the term “systems design” was used here. But later during the presentation, I think I know: it denotes a manual whose structure is based on the structure of the user interface it’s describing, rather than on user tasks.)

Minimalist design

Marta talked through these points of minimalist design:

Brief orientation
Prerequisite tasks
Learn by doing, start straight away
Modular, self-contained topics
Support error recognition/recovery

We looked at an example of a legacy document, which was organised to match the menu structure of the user interface. Barbara described how she reorganised the document along minimalist principles. She started by identifying the key user roles (booking officer, investigator, administrator) and their key tasks (create booking records, search for new records, etc). The new guide was then organised on sections based on tasks (use the import queue, create inquiry records, create booking records, etc).

Questions from the audience

At this point, a member of the audience said that the minimalist guide would be more of a quick-start guide, but a comprehensive user manual is still required. Barbara’s answer was that a system-organised reference manual is typically not used very much. Users typically want to find their information within the context of the key business task. If it’s important to explain specific elements of the screen, do it as part of the business task.

A number of related questions arose, which Barbara answered authoritatively and clearly. One audience member made the point that you could start with the minimalist guide and allow people to drill down to the more detailed information. Barbara also said that part of the role of technical writer is to point out what the primary focus is: serving the users’ needs based on usability studies. We don’t need to document everything that other people tell us to document.

Psychology of learning

Barbara related the principles of minimalist design to the psychology of learning, which shows that we are complex, emotional beings, not machines that run scripts. We do things for complex reasons, without necessarily understanding the reasons ourselves. We need to act, even to struggle, in order to learn and to retain information. People may even be too busy learning to spend much time on the instructions.

Developing minimalist documentation

Examine the system you’re documenting, decide where it’s not intuitive to use, and help the user with those areas. Discover the user’s mental model, and find out if it matches how the tasks are carried out in the system. If not, help orient them to the system. Find the common error situations, and help users through them.

Thanks Barbara

I’ve never consciously used minimalist design, although I’ve attended a few talks on it through the years. I feel that some of the principles have rubbed off on me. This talk helped crystallise and solidify the concepts and practise of minimalism for me.

Google Glass and Augmented Reality (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

Early on Tuesday morning, Marta Rauch spoke about “Google Glass and Augmented Reality – Tools for your Content Strategy Toolkit“.

Although I work at Google, I don’t have anything to do with Google Glass and don’t own a Glass device myself, so I was very interested to hear Marta’s experiences with it and her ideas on integrating it with content strategy.

This session was one of the ten virtual track sessions of the conference, which means that people around the world were listening in and participating. This is a new initiative by the STC. Very cool.

Overview

Marta’s talk covered the following aspects of how augmented reality and Google Glass affect technical communication:

 The market for wearable technology
Google Glass apps and use cases
The importance of augmented reality
Content strategy
Resources

Main takeaway

From Marta: These are two technologies we need to pay attention to, and we need to think how our content will look if we’re asked to develop for augmented reality or Google Glass.

Marta did a quick poll of the audience: approximately 20% had used wearable technology. Marta has noticed from the polls she takes during presentations that the number of people using wearable tech is growing. This is similar to the way mobile usage grew during its early adoption. She also showed us that the results of a survey showing that 27% of developers in 2014 plan to create apps for wearable tech.

Google Glass UX and apps

We had a quick look at what it’s like to use Google Glass: the menu that appears when you first say “OK Glass”, and the settings available. Marta remarked that the Glass user interface is very visual: lots of pictures/graphics and few words.

The apps on Google Glass are called “Glassware”. Marta showed us some pics of a spelling game, Twitter, Google+, voice translation, and more. “You can just speak instead of having to type. It’s really really handy.”

Marta also talked about Tesla and Mercedes, who are developing integrations that allow you to interact with your car via Google Glass.

Then there’s a doctor who’s using Glass to train medical students, and in surgeries. Surgeons put their content on Glass and do a webcast from the surgery, getting a second opinion from colleagues without needing to use their hands.

Marta showed a number of other very cool use cases and apps, including some that benefit people with disabilities. Then there’s fashion photography via Glass, cooking and recipe apps, news, shopping, workout… Many more.

Questions from the audience about the effect on your vision

At this point, two questions came from the audience:

Is Google Glass bad for your vision? Marta has discussed this with her optometrist. He said that Glass should not have a negative effect on her vision. In fact, Marta is short sighed, and her personal experience has been that her vision has improved slightly over the last year when she’s been using Glass. This is not due to Glass, but Glass has certainly not negatively affected her vision. Nevertheless, Marta recommends that you take regular breaks when using any type of technology.
Can you wear Google Glass with your regular prescription glasses? You can attach Google Glass to regular glasses frames, or put Glass over your glasses. And you can wear it with contact lenses.

The importance of augmented reality (AR)

What is AR? Marta showed us how a device such as a smart phone or Google Glass can add context and content to a magazine article. AR is something that enhances a person’s experience of reality by adding an overlay of digital information. The overlay could be an image, text, or other information.

Marta showed us some AR apps for Google Glass and wearable technologies. Theres an app that shows you how you’re doing in a running race. Or a car app that can show fuel levels, lifetime milage, oil life and tyre information.

AR is everywhere. 864 million phones are AR enabled now. 103 million cars will be AR enabled by 2020. It’s also big money, with the potential to generate a revenue of $600 billion by the end of 2016.

Marta listed the fields that are taking advantage of AR, including repair industries, surgery, automotive, mobile, and more. AR is replacing manuals, such as automotive repair guides.

Content for wearable tech

Marta gave some hints on how to write content for wearable technologies:

It must be useful.
Make it timely and relevant – just what you need to know, when you need to know it.
It must be unobtrusive.
Concise. Use few words.
Straightforward. You don’t know where the person is. Make the language colloquial and conversational. Marta’s colleagues have developed some guidelines which she can share.
Make it visual: graphics are easy and quick to understand.
Make it adaptable. The content must work across different devices.
It must be accessible. Follow the accessibility guidelines of your organisation.

Thanks Marta

It was great to see the progress Google Glass, wearable tech, and augmented reality have made over the last year. So many apps and use cases. This presentation clearly shows how important these new technologies are, and that we need to design our content accordingly.

API technical writing (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Yesterday it was my turn to present a session.

My presentation was titled, “API Technical Writing: What, Why and How“. (The link is to the slides on SlideShare.) My aim was to introduce technical writers to APIs (Application Programming Interfaces) and to the world of API documentation. I hoped it would be useful to writers who’ve had very little exposure to APIs, as well as to those who’ve played with APIs a bit and want to learn about the life of an API technical writer.

Overview

Here’s a summary of the presentation:

Introduction to the role of API technical writer.
Overview of the types of developer products we may be asked to document, including APIs (application programming interfaces), SDKs (software development kits), and other developer frameworks.
What an API is and who uses them.
Examples of APIs that are easy to play with: Flickr, Google Maps JavaScript API
Types of API (including Web APIs like REST or SOAP, and library-based APIs like JavaScript or Java classes).
A day in the life of an API technical writer—what we do, in detail.
Examples of good and popular API documentation.
The components of API documentation.
Useful tools.
How to become an API tech writer—tips on getting started.

Demo of the Flickr API

I did a live demo of the Flickr API. It worked! The demo gremlins hadn’t found me yet. :) If you’d like to play with this API yourself, take a look at the Flickr Developer Guide (and later the Flickr API reference documentation). You’ll need a Flickr API key, which is quick and easy to get. Slide 23 in my presentation shows the URL for a simple request to the Flickr API.

Demo of the Google Maps JavaScript API

My second demo showed an interactive Google map, embedded into a web page with just a few lines of HTML, CSS and JavaScript. I used the Google Maps JavaScript API. If you’d like to try it yourself, you’re welcome to start by copying my code. It’s on Bitbucket: HelloMaps.HTML. This code is what you’ll find on slide 28 in my presentation.

Feeling adventurous? Grab another set of code, which adds a weather and cloud layer to the map: HelloMapsWeather.HTML.

More links

There are more links to follow in the presentation itself: API Technical Writing: What, Why and How. I hope you enjoy playing with some APIs and learning about the life of an API technical writer!

Key Trends in Mobile Publishing (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

During the opening session yesterday, Vikram Verma presented a very interesting snippet on mobile publishing trends. So I decided to attend his full-length presentation today. Vikram represents Adobe, one of the conference sponsors.

Vikram’s session covered the following topics:

Why you should care about multi-screen publishing.
Key mobile publishing trends in tech comm
Challenges and solutions
A demo of multi-device publishing with Adobe products

Trends

Looking at the four publishing output formats that companies are using for their mobile publications, Vikram gave the current state and a projected state for the near future:

HTML 5 is the most dominant with currently 28%, expected to rise to 48%
EPUB is now at 12% and will rise to 24%
Kindle is at 5%, rising 10%
Android is at 11%, expected to grow to 25%

Mobile publishing and structured authoring are the two strongest trends in technical communication.

How can you make your mobile publications user friendly?

Think about the new formats, rather than legacy formats such as PDF and web help. Legacy formats offer problems like:

Difficult to read. Zooming in can be problematic.
Not touch friendly. Icons and buttons are compressed on small devices.
Difficult to navigate.
Offer slow loading on a mobile device.

Be aware that attention spans are short, and design your pages accordingly. Research shows that the smaller the device, the lower the attention span. People are more likely to abandon your mobile content if they don’t like it. Also, people are five times more likely to abandon the task if the site isn’t optimised for mobile. Conversely, people are using their smart phones more than their desktops to browse the web. So you’re losing even loyal customers, who are now trying to access the content on the web.

Another challenge is device fragmentation. Mobile phones and tablets come in all sorts of sizes. People are even watching our content on their TVs.

Potential solutions

This is my summary of the solutions Vikram discussed at length:

Use responsive design. This allows the page format to change dynamically, depending on the output device. Vikram showed us a few responsive websites: Time Magazine, Mashable, CSS Tricks. Responsive design is a prominent trend in website design.
Use adaptive content. That is,  offer different content for different devices. One way is to have separate mobile websites. This is a very prevalent way of doing it, used by a number of big web companies, such as Google and Facebook.
Create mobile apps. This is a good way to offer a good experience for customers. It’s a way of delivering content for users when online access isn’t always available. (If you’re using HTML 5, the user needs to be online.)
Adopt a hybrid approach. Responsive design, but with some server-side components: RESS (Responsive Design with Server Side). Examples of sites using this approach: CNN, WordPress, SlideShare, eHow. To publish using RESS, you will define the device categories. For example, define categories for phones, tablets, desktops. For these categories, define the content and the layout. Use a server-side component to merge the content and layout definitions into an output format.

Vikram now talked through a matrix comparing the pros and cons of each approach in the following categories:

Mobile users’ needs
Ease of maintenance
SEO
Loading time and performance

The choice depends on the context and the end users’ environment.

Vikram finished with a demo of RESS using Adobe’s RoboHelp.

Thanks

This was an information-packed session, with plenty of opportunity for further investigation. Thanks Vikram!

How technical writers can build personal influence (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

Bright and early on Monday morning, Kevin Lim presented a session titled “Influence Strategies and Tactics for Technical Writers”.

Kevin started by saying that the title of her project was really just a fancy-pants way of saying “office politics 101″. This prompted a big laugh.

She mentioned the triple constraints of a project: Time, scope and cost. In the ideal world, your success depends on your ability to manage these three constraints. But the world isn’t ideal: what if you have people who are difficult to work with? What tools does a technical writer have to manage such a project?

Influence! This is the dark matter of project management. You don’t see it or put it into your plan, but it has a large effect. Even if you have no formal authority, you can have influence. We as writers may not have positional authority, we can have personal authority. To gain such authority, you need to build up a large network of contacts. Another way of gaining authority is to establish yourself as an expert.

Kevin’s session focused on the four main things you need to do, to become influential:

Figure out your company culture and strategy. Find out what matters to your company. Common goals can bind all of you together. Kevin walked us through some methods we can use to analyse the strategies and culture that drive our organisations.
Identify the key people. They are part of a network of circles: experts, supporters (people you trust), and associates (people you work with). Kevin talked about knowing your own circles, the circles involved in an issue, and the circles of key people. This helps you know who you should approach when you encounter an issue, or need an answer, or want to know who or what is influencing key people. Be engaged and aware of the environmental influences that are affecting your project, whether you like it or not.
Apply the principles of influence to get people to cooperate with you. People help you when they feel like it. Kevin talked about the principals of influence, as outlined by social psychologists, and gave amusing and useful examples of how we can apply them to a technical writing project.
Pick the right communication style. Learn how to ask. People have different communication styles. Kevin spoke about the four personality types (analytical, amiable, driver, and expressive) and the preferred communication style of each.

Thanks to Kevin for an authoritative and interesting presentation. This was a very in-depth presentation, and my notes can in no way do justice to it.

Content strategy versus wicked ambiguity (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

I’ve just arrived in Phoenix, Arizona, this year’s host city. It’s around 40 degrees Centigrade, or 100 Fahrenheit. Phew! But I’m sure the temperature will be just one of the hot topics at this conference. ;)

The keynote presentation was given by Jonathon Colman, content strategist at Facebook.

Wicked Ambiguity, by Jonathan Colman

Jonathon started with a big smile and the sage saying, “Don’t worry, everything’s going to be fine.” It’s the sort of thing we say to children. But we live in a world of uncertainty. That’s what this talk is about.

Jonathon told us stories from Stephen King (“that shape under the sheet could be anything – anything at all”) to Claude Shannon, the father of information theory (a diagram of communication from the 1940s that is still relevant today).

He then ran through the diversity of roles technical writers fill: writer, designer, information architect, content strategist, and more. Despite our diversity, we stand united against ambiguity. We make the complex simple.

But what if we were writing a message, without knowing who would try to interpret it? Jonathan went over two scenarios that present this problem. It’s one of those unsolvable problems – one which needs a different type of solution: a “wicked problem”.

Some examples of wicked problems:

Jonathon showed us the well-known map of the Cholera outbreak in 19th century London, showing the highest incidences of cholera in relation to the location of the water sources. This is how John Snow saved London and invented the field of epidemiology.
Another map showed the incidence of Ebola virus in West Africa.
The war on drugs is another example of a wicked problem, where the interdependencies resist resolution.
 And climate change. We’re just now understanding how this effects everything, from climate to politics.

Jonathon spoke of two wicked problems in technical communication:

1) Communicating with aliens

Jonathon emphasised that this is not science fiction. He launched into a few amusing stories about scientists who’d had bright ideas to communicate with whoever is out there in the universe, such as drawing triangles in the Siberian tundra or burning messages onto Mars.

He then showed the engraved diagram and symbols designed by Carl Sagan, that were sent out with Pioneer spacecraft. And followed up with other condensed, rich and layered messages sent into space, such as the audio and visual messages sent on the Voyager spacecraft in the 70s. Jonathan says Carl Sagan is possibly the greatest technical communicator ever.

But what will an alien civilisation make of this? Will they even be able to play it? Will they be able to interpret it? And what will they do as a result of receiving the message?

Uncertainty rules.

2) Nuclear semiotics

We have nuclear weapons and nuclear power plants. Both leave behind nuclear waste. How do we communicate the dangers of this waste to future generatios who might come across it? That’s the problem of nuclear semiotics.

Plutonium 239 has a half-life of more than 24 000 years. To be safe, it has to remain untouched for nearly 100 000 years.

Uranium 235 has a half-life of nearly 704 million years.

Looking back at our past, we note that language is a fairly new invention. Thus, communicating the danger of nuclear waste is wicked problem.

The US created the Human Interference task force, with this mission: Stop humans coming into contact with nuclear waste. Their task was to create a message capable of being interpreted for over 10 000 years.

One of the suggested solutions was to create a religious priesthood, the Atomic Priesthood. The reasoning is that religions are one of the few things that last over a long period.

Another idea was to launch a global network of satellites that would constantly communicate the location of the nuclear waste sites. Or to create some genetically modified plants that would only grow near the sites, and would contain encoded information about the composition of the waste. Plants as a medium for technical communication!

Yet another idea: Ray Cats – cats that would glow in the presence of nuclear radiation. Reasoning: Humans have a long-lasting association with cats. (After all, smiled Jonathon, we created the Internet to immortalise cats. This got a good laugh from the audience.)

Jonathon listed a few more approaches to the problem of keeping future humans away from nuclear waste.

We don’t know what the effect of these messages will be on the intended audience. They may not work.

Wicked problems are everywhere. They’re catalysts. They change us, and ignite our creativity. They make us think, they force us to solve them, and that’s how we evolve.

Ambiguity and technical communication

Jonathon finished off by returning to ambiguity and its relationship to our role as technical communicators.

Ambiguity, uncertainty, and the unknown are part of every-day life.

Some people are terrified of uncertainty, but technical communicators grapple with it routinely. We ask the hard questions, instead of passing that ambiguity onto our customers.

Technical writers communicate complex information in a way that is clear and simple. We can’t solve the wicked problems, but we can try. And that effort is what we do best.

Thanks Jonathon

This presentation was a great start to STC Summit 2014. Jonathon is an amusing, engaging speaker. He filled the room with laughter and with enthusiasm for our field of technical communication.

Introducing Tech Comm on a Map

I’ve been working on a personal project, and I’m delighted to say it’s ready to share with you! The idea is to help us see what’s happening around the globe, in the world of technical communication. So I’ve put tech comm titbits onto an interactive map, together with the data and functionality automatically provided by Google Maps. To see it in action, go to Tech Comm on a Map.

At the time of writing this post, Tech Comm on a Map contains information of the following types, all related to technical writing and technical communication:

Conferences (purple circles)
Societies (yellow circles) – includes societies and associations.
Other (blue circles) – a grab bag to catch anything that doesn’t fit into the first two categories. This is also the default category for data items that aren’t correctly categorised.

To find the information, click one of the coloured circles on the map. You can also zoom into a particular city or address, by entering the place name or address in the search box.

Where does the data come from?

It’s all in a Google Docs spreadsheet. Up to now, I’ve collected and entered the data myself. I’ve scoured the Web for information about conferences. I’ve also added just a few societies, and a couple of ‘other’ items to prove the category exists. The spreadsheet looks like this:

Spreadsheet containing tech comm data for map

What’s the plan for adding more data and maintaining what’s there?

My plan is to invite a few people to help update the spreadsheet that holds the data.  Any data added to the spreadsheet appears on the map immediately. It’s pretty cool!

How does it work?

The tools I’ve used are the Google Maps JavaScript API, the Google Places Autocomplete widget, and Google Apps Script to extract the data from a spreadsheet in Google Sheets. The code and website are hosted on GitHub.

I’ll write another post soon, with more details about the code and the APIs.

Am I planning to add anything more to the project?

There is plenty of potential for enhancements. For example, we could add more categories to the existing three (conferences, societies, and other) to include events like technical writers’ group meetings. We could add styling to the map. And other sweetening we can think of…

A number of people have already made some exciting suggestions for v2. The project is open source, so if you have an improvement to suggest, send me a pull request. :)

Feedback

I’d love to know what you think of the map, and whether you’re excited about adding more events and other types of tech comm titbits! If you’d like to share your ideas, please add comments to this post.

Get ready for APIs at STC Summit 2014

STC Summit 2014 is fast approaching! The conference starts in Phoenix AZ on Saturday May 17th. I’ll be speaking on Monday afternoon, on the topic of API Technical Writing: What, Why and How. My aim is to inspire people about APIs: how much fun they are, how developers use them to build useful, fascinating, inspiring software, and how we as technical writers can help by providing the essential documentation and other assistance.

In my session, we’ll take a look at what an API is, and see two popular APIs in action: The Flickr API and the Google Maps JavaScript API. Then we’ll move on to the technical writing side of things: what an API technical writer does, and what good API documentation looks like.

Part of the discussion will be about different types of APIs: web services, JavaScript APIs, object-oriented libraries, and more. There won’t be enough time to cover this aspect in depth, so as an adjunct to the session I’ve put up a short slide deck that accompanies my recent blog post about API types. The blog post has a link to the slide deck, as well as more detailed information about API types. Check out the comments on the post too, for knowledge shared by others.

I’m greatly looking forward to all the sessions and meetups at STC14. I hope to see you there!