Blog Archives

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.

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!

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.

API types

I’m putting together a list of the various types of API we might encounter. This is primarily a resource for technical writers, who may need to know what type of thing they could be asked to document if they take on the role of API tech writer.

A Google search didn’t reveal much material about API types. The best source of information is the Wikipedia page on APIs.

I tried searching for “API classification” and received plenty of information about engine oil. :D

So here goes… my attempt at an API classification.

Update: Content now available in a slide deck too

3 May 2014: I’ve created a slide deck which summarises the information in this post and includes some information from the comments on the post and from discussions with other tech writers. The slide deck is available on SlideShare:

Link to the slides on SlideShare

Before we start: What is an API?

API stands for “application programming interface”. Put briefly, an API consists of a set of rules describing how one application can interact with another, and the mechanisms that allow such interaction to happen.

What is an interaction between two applications? Typically, an interaction occurs when one application would like to access the data held by another application, or send data to that app. Another interaction might be when one application wants to request a service from another.

A key thing to note: An API is (usually) not a user interface. It provides software-to-software interaction, not user interactions. Sometimes, though, an API may provide a user interface widget, which an app can grab and display.

There are two primary benefits that an API brings:

  • Simplification, by providing a layer that hides complexity.
  • Standardisation.

Examples:

  • Microsoft Word asks the active printer to return its status. Microsoft Word does not care what kind of printer is available. The API worries about that.
  • Bloggers on WordPress can embed their Twitter stream into their blog’s sidebar. WordPress uses the Twitter API to enable this.

Web service APIs

A web service is a piece of software, or a system, that provides access to its services via an address on the World Wide Web. This address is known as a URI, or URL. The key point is that the web service offers its information in a format that other applications can “understand”, or parse.

Examples: The Flickr API, the Google Static Maps API, and the other Google Maps web services.

A web service uses HTTP to exchange information. (Or HTTPS, which is an encrypted version of HTTP.)

When an application, the “client”, wants to communicate with the web service, the application sends an HTTP request. The web service then sends an HTTP response.

In the request, much of the required information is passed in the URL itself, as paths in the URL and/or as URL parameters.

For example:

http://maps.googleapis.com/maps/api/staticmap?center=Sydney,NSW&zoom=14&size=400x400&sensor=false

In addition to the URL, HTTP requests and responses will include information in the header and the body of the message. Request and response “headers” include various types of metadata, such as the browser being used, the content type, language (human, not software), and more.

The body includes additional data in the request or response. Common data formats are XML and JSON. The process of converting data from internal format (for example, a database or a class) to the transferrable format is called “data serialization”.

Most often-used types of web service:

  • SOAP
  • XML-RPC
  • JSON-RPC
  • REST

SOAP (Simple Object Access Protocol)

SOAP is a protocol that defines the communication method, and the structure of the messages. The data transfer format is XML.

A SOAP service publishes a definition of its interface in a machine-readable document, using WSDL – Web Services Definition Language.

XML-RPC

XML-RPC is an older protocol than SOAP. It uses a specific XML format for data transfer, whereas SOAP allows a proprietary XML format. An XML-RPC call tends to be much simpler, and to use less bandwidth, than a SOAP call. (SOAP is known to be “verbose”.) SOAP and XML-RPC have different levels of support in various libraries. There’s good information in this Stack Overflow thread.

JSON-RPC

JSON-RPC is similar to XML-RPC, but uses JSON instead of XML for data transfer.

REST (Representational state transfer)

REST is not a protocol, but rather a set of architectural principles. The thing that differentiates a REST service from other web services is its architecture. Some of the characteristics required of a REST service include simplicity of interfaces, identification of resources within the request, and the ability to manipulate the resources via the interface. There are a number of other, more fundamental architectural requirements too.

Looked at from the point of view of a client application, REST services tend to offer an easy-to-parse URL structure, consisting primarily of nouns that reflect the logical, hierarchical categories of the data on offer.

For example, let’s say you need to get a list of trees from an API at example-tree-service.com. You might submit a request like this:
http://example-tree-service.com/trees

Perhaps you already know the scientific name of a tree family, Leptospermum, and you need to know the common name. You request might look like this:
http://example-tree-service.com/trees/leptospermum

The tree service might then send a response containing a bunch of information about the Leptospermum family, including a field “common-name” containing the value “teatrees”.

An example of a REST API: The JIRA REST APIs from Atlassian.

The most commonly-used data format is JSON or XML. Often the service will offer a choice, and the client can request one or the other by including “json” or “xml” in the URL path or in a URL parameter.

A REST service may publish a WADL document describing the resources it has available, and the methods it will accept to access those resources. WADL stands for Web Application Description Language. It’s an XML format that provides a machine-processable description of an HTTP-based Web applications. If there’s no WADL document available, developers rely on documentation to tell them what resources and methods are available. Most web services still rely on documentation rather than a machine-readable description of their interface.

In a well-defined REST service, there is no tight coupling between the REST interface and the underlying architecture of the service. This is often cited as the main advantage of REST over RPC (Remote Procedure Call) architectures. Clients calling the service are not dependent on the underlying method names or data structures of the service. Instead, the REST interfaces merely represent the logical resources and functionality available.  The structure of the data in the message is independent of the service’s data structure. The message contains a representation of the data. Changes to the underlying service must not break the clients.

Library-based APIs

To use this type of API, an application will reference or import a library of code or of binary functions, and use the functions/routines from that library to perform actions and exchange information.

JavaScript APIs are a good example. Take a look at the Google Maps JavaScript API. To display an interactive Google Map on a web page, you add a <script> tag to include the JavaScript library provided by Google. Then you write your own JavaScript code, calling the Google Maps functions as needed.

Another example is the JavaScript Datastore API from Dropbox. And the Twilio APIs offer libraries for a range of languages and frameworks, including PHP, Python, JavaScript, and many more.

TWAIN is an API and communications protocol for scanners and cameras. For example, when you buy an HP scanner you will also get a TWAIN software library, written to comply with the TWAIN standard which supports multiple device types. Applications will use TWAIN to talk to your scanner.

The Oracle Call Interface (OCI) consists of a set of C-language software APIs which provide an interface to the Oracle database.

Class-based APIs (object oriented) – a special type of library-based API

These APIs provide data and functionality organised around classes, as defined in object-oriented languages. Each class offers a discrete set of information and associated behaviours, often corresponding to a human understanding of a concept.

The Java programming community offers a number of good examples of object oriented, or classed-based, APIs. For example:

  • The Java API itself. This is a set of classes that come along with the Java development environment (JDK) and which are indispensable if you’re going to program in Java. The Java language includes the basic syntax and primitive types. The classes in the Java API provide everything else – things like strings, arrays, the renowned Object, and much much more.
  • The Android API.
  • The Google Maps Android API.

As an example for C#, there’s the MSDN Class Library for the .NET Framework. The Twilio APIs mentioned above also include both Java and C#.

Functions or routines in an OS

Operating systems, like Windows and UNIX, provide many functions and routines that we use every day without thinking about it. These OSes offer an API too, so that software programs can interact with the OS.

Examples of functionality provided by the API: Access to the file system, printing documents, displaying the content of a file on the console, error notifications, access to the user interface provided by the OS.

Object remoting APIs

These APIs use a remoting protocol, such as CORBA – Common Object Request Broker Architecture. Such an API works by implementing local proxy objects to represent the remote objects, and interacting with the local object. The same interaction is then duplicated on the remote object, via the protocol.

As far as I can tell, most of these APIs are now considered legacy. Another example is .NET Remoting.

Hardware APIs

Hardware APIs are for manipulating addressable pieces of hardware on a device – things like video acceleration, hard disk drives, PCI buses.

Other developer products

There’s more to life than APIs, of course. :) A technical writer may be called upon to document other developer-focused products:

  • SDKs – software development kits, which typically contain a set of tools that developers use to interact with, and develop on top of, your product.
  • IDE plugins – custom additions to standard development environments, which give developers the extra tools they need to interact with your product from within a development environment like Eclipse, IntelliJ IDEA, or Visual Studio.
  • Code libraries that developers can import into their projects.
  • Other frameworks that support software development in a specific environment, such as custom XML specifications, templates, UI guidelines.

There’s more than one way to can has a cat

Your turn. What have I missed, and are there more useful ways of classifying APIs?

Follow

Get every new post delivered to your Inbox.

Join 1,495 other followers

%d bloggers like this: