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?
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.
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.
‘Login’ or ‘log in’? One word or two? It’s an oft-debated question. I’m not proposing a hard-and-fast rule, though I do have my preferences. What this post offers is a handy way of choosing between one word and two, if it’s important to you.
It’s not just logging in that’s affected. There are plenty more cases where we need to choose one word or two:
- ‘logon’ or ‘log on’
- ‘logout’ or ‘log out’
- ‘signup’ or ‘sign up’
- ‘shutdown’ or ‘shut down’
- ‘backup’ or ‘back up’
- ‘setup’ or ‘set up’
- and more, including words not related to computing, such as ‘workout’ versus ‘work out’
Who’s up for an experiment?
Warning: Don’t try this at home, unless your partner is in a good mood.
Try speaking these sentences out loud, replacing ‘bbbbbbb’ with ‘backup’ and ignoring the spelling for now:
- What is your bbbbbbb strategy?
- When did you last bbbbbbb your data?
- When did you last do a bbbbbbb?
Now try these, replacing ‘llllllll’ with ‘login’:
- What are your llllllll details?
- Where can I llllllll to the bank’s website?
- My llllllll failed.
Did you notice any pattern in the way you pronounced the words “back/up” and “log/in”? If you’re like me, your stress pattern in the middle sentences would be different from the first and third sentences.
- In the middle sentence, you would give equal emphasis to both parts of the phrase: back up; log in.
- In the first and third sentences, you would give greater emphasis to the first part of the phrase: backup; login.
And the answer is…
‘Backup’ or ‘back up':
- What is your backup strategy?
- When did you last back up your data?
- When did you last do a backup?
‘Login’ or ‘log in':
- What are your login details?
- Where can I log in to the bank’s website?
- My login failed.
Rules and things
It may be that you decide to go with the growing common usage, and just use one word (like ‘login’) for everything. But if you want to follow the ‘rules’, they’re something like this:
- If it’s a verb, use two words.
- If it’s a noun, including cases when the noun is used to qualify another noun, use one word.
What about hyphens (‘-‘)? Technical writers try to avoid them.
Who decreed that this is how it’s done, and where is it written down? Most tech writers and other guardians of language would agree that we should be descriptive rather than prescriptive, and that there are a equally-viable alternatives out there. But we also agree that it’s good to have a standard, so that our readers have a smooth ride through the documentation and application screens.
Here are some style guides and commentaries that agree we use one word for a noun, two for a verb:
- Guardian and Observer Style Guide – Scroll down to the entries for ‘log in’ and ‘login’.
- Apple Style Guide – See the entry for ‘log in (v.), login (n., adj.), log out (v.), logout (n., adj.)‘, on page 96.
- Log in vs. login by Grammarist – This post has some useful examples from online newspapers.
- A thread on the English Language and Usage Stack Exchange – People express various opinions, but the consensus is one word for a noun, two for a verb.
- Another thread on the English Language and Usage Stack Exchange – This one is particularly cool, because someone pointed out in a comment that the instructions on the Stack Exchange page itself said ‘Sign up or login’, and Stack Exchange fixed it!
- The Wikipedia page on login – The page consistently uses ‘login’ as a noun and ‘log in’ as a verb. It also states, ‘The noun login comes from the verb (to) log in‘.
- And someone who has a strong opinion, backed up by good research: “Login” is not a verb.
Who cares? Is this a difference between US and British usage? I don’t think so. It’s more a difference between people who feel a sense of jarring disconnect when someone uses ‘login’ and the like as a verb, and people who don’t. If you do want to differentiate, the pronunciation test may be the quickest way to decide whether you need one word or two.
There’s only one word for this spider: Eek!
This spider took up residence between my window panels for a while. It’s a huntsman: huge, very fast, scary but beautiful, and largely harmless. I put the peg there for scale. It’s a large peg.
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:
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.
- 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.
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.
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 (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 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 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:
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:
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.
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.
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.
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 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?
I’m curious to see how things have changed since I last asked this question, back in March 2012: What’s your favourite API documentation, and why?
Part of the reason for asking is that I’ll soon present a session at STC Summit 2014 on API technical writing. I want to give examples of excellent documentation. I have some favourite documentation sets myself, but it’s great to get the opinions of developers and other technical writers too.
So, have at it! :) Please comment on this post.
What’s your favourite API documentation, and why?
I’ll also collect any suggestions that people send via Twitter, Google+, and other channels, and add the links to this post.
OT: This has to be the world’s best bird. Well, it’s my current favourite anyway. This is a Tawny Frogmouth, spotted on an early morning walk. Tawny Frogmouths are night birds, about the size of a large owl (34-52 centimetres). During the day, they pretend to be old tree branches.
I’ll be speaking about API technical writing at STC Summit 2014. Part of the presentation is about useful tools for API technical writers. Since there are already some great resources on the Web about editors and IDEs, I plan to focus on a motley collection of “other” tools. Those that do a specific job very well. Those of which you’d say, “When I need it, I really need it.”
There are plenty of blog posts and articles about tools for documentation and code, including open source tools. Particularly when talking about editors and IDEs (Integrated Development Environments) most people have their favourites. The debates about which tool is best can get quite fiery!
Here are some useful links:
- Mike McCallister’s presentation, Open Source Tools for User Assistance. It’s well worth following Mike’s blog too.
- Chantel Brathwaite, writing on the TechWhirl blog about Technical Writing on a Shoestring.
- From Bret McGowen on the Rackspace blog, My Text Editor Final Four.
So, aren’t you going to talk about editors at all? ;)
My favourite IDE is Eclipse. I like to dabble in Android Studio and IntelliJ IDEA, just to see what’s happening.
Now that’s out of the way, let’s look at some super-useful and less-talked-about tools for API tech writers in particular.
Syntax highlighter for code samples
I frequently need to add a code sample to an HTML page, or include a slice of code in a presentation. Code is much easier to understand if the text is highlighted to indicate method names, variable declarations, and other syntactical essentials. And it just looks prettier too.
hilite.me converts a code snippet into styled HTML, which you can copy and paste into your page. Paste in your code, and select the coding language, to get the appropriate highlighting. Then click “Highlight!” to see the result. You can grab the HTML and CSS code, or copy and paste the highlighted text itself. You can even choose from a number of styles, such as “colorful”, “friendly”, “fruity”, and so on.
For example, I pasted in a Java “hello world” class, and asked for “tango” style highlighting. The “Preview” box at the bottom of this screenshot shows the result:
Testing web services and REST APIs
There’s an add-on for Chrome browser, called the Advanced REST Client, which I find very useful for getting examples of web service requests and responses. You can craft an HTTP request, then submit the request and see the response. This is a nice GUI alternative to a command-line tool like cURL.
Let’s say I want to use the Google Geocoding API to get a human-readable address for a pair of latitude/longitude coordinates. My URL would look like this:
I’ve pasted the above URL into the Advanced REST Client tab in Chrome, then used the add-on to expand the URL parameters, making it easy to see the composition of the HTTP request:
Now press the “Send” button to see the response. This is a partial screenshot:
Very handy indeed.
Chrome Developer Tools
The Chrome Developer Tools are a little tricky to grok, but once you’ve figured out what’s going on, they’re coolth personified. To find them, click the three-barred icon at top right of the Chrome window (the tooltip says “Customize and control Google Chrome”) then choose “Tools” > “Developer Tools”. The keyboard shortcut is Ctrl+Shift+I or Cmd+Shift+I.
A panel opens at the bottom of the page. It’s pretty busy, so take your time getting used to it. You can click an option to undock the panel and see it as a separate window, if you prefer that. In this screenshot, the DevTools panel is open at the bottom of the screen, and is showing the “Elements” tab:
There are many many things you can do with the DevTools. The Chrome DevTools documentation is a good guide. These are the functions I use most often:
- Check which CSS style is in effect on a particular block of HTML. This is particularly useful when there are a number of stylesheets at play. Sometimes the cascading effect of CSS doesn’t seem to follow the laws of gravity!
- Watch the error messages scrolling past on the “Console” tab. :)
- Edit HTML on the spot, to see the effect live on a web page before putting my changes into the source code.
Open Device Labs – Access to real devices and platforms for test-driving an app
It can be very difficult to try out an application on every supported device or platform. Especially for those of us dealing with mobile apps, there are just way too many devices out there for it to be feasible to have an example of each one.
One solution is to use emulators. But here’s an exciting initiative that I heard about recently: Open Device Labs.
The idea is that people may have last year’s mobile phone lying around, that they’d be willing to allow other people to use for testing. Some people may even want to donate new devices to the cause. Smart, enthusiastic people have set up hubs of Internet-connected devices at various locations around the world, and made them available to us all to use. For free!
I haven’t yet used a device from one of these labs, but the idea is awesome. What a great way to test an app, get screenshots, figure out the “how to” instructions you need to write, and just see how the user experience feels.
Mobile emulator in Chrome browser
With Chrome’s mobile emulation, you can make your desktop browser pretend that it’s something else. It can masquerade as an iPhone, Kindle, Blackberry, Nexus, and more. This is very useful for taking screenshots, and for seeing how responsive an app is to different device sizes and resolutions. The emulator is available via a fairly obscure setting in the Chrome Developer Tools panel.
Online source repositories are good for sharing code. In a tutorial, it works well to include code snippets and point readers to the complete source in a repo. Bitbucket and GitHub are very popular. I have accounts on both, because I’ve worked with teams on both. GitHub works with Git, while Bitbucket supports both Git and Mercurial.
That’s my list so far. If I find any more tools before the STC Summit in May, I’ll add them to the list I’m creating for my presentation. It will be fun to share them with the tech writers at the conference. Can you think of any super-useful tools to add to the list?