Author Archives: Sarah Maddox

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.


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.


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


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.


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. Here’s a link to Jonathon’s presentation on SlideShare: Wicked Ambiguity: Solving the Hardest Communication Problems.


Get every new post delivered to your Inbox.

Join 1,446 other followers

%d bloggers like this: