Author Archives: Sarah Maddox

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 influences, including books, articles and methodologies. These include DITA, content strategy, Information Mapping, Every Page is Page One by Mark Baker, and more.

Update on 14 June 2014: The above paragraph previously stated, erroneously: “She also gave us a useful list of references to books, articles and methodologies that have influenced minimalism.” I have now changed it to say, “She also gave us a useful list of influences, including books, articles and methodologies.”

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.


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.


Get every new post delivered to your Inbox.

Join 1,447 other followers

%d bloggers like this: