Business Computer Languages Language Process Tools Training Uncategorized Useful Links Writing

Designing Effective API Documentation

The user interface of an application – even one with a convoluted design – gives users some sense about how to navigate the application. It may be painful, but users can usually muddle through if they have to. APIs, on the other hand, offer no natural affordances or signifiers allowing developers to learn how to use the API. Therefore, good documentation is crucial for any API project.

Blogroll Business Captivate Flare Humor? Language Process Rants ROI Tools Training Uncategorized Water Cooler Stuff Writing

Why User-Centered Design Matters

When was the last time you used an application that was just impossible to comprehend?

Shaun Article 1





Shaun Article 2














Or that you visited a web page that made it hard to find what you were looking for?

Shaun Article 3











I’m guessing you don’t have to rack your brain too hard to come up with an example. In fact, if you’re reading this at work, you might very well have opened our newsletter just to take a break from the confusing enterprise software you’re stuck using for your job.

The Science Behind the Suck

During World War II, Army Air Force scientists noticed that changes in cockpit design often had disastrous effects on pilot performance. When the mental and physical capabilities of pilots did not align with the design of the aircraft, pilots were much more likely to make a mistake. Considering these “human factors” as part of the design turned out to be an important safety and performance issue. This insight led to a new science that linked human psychology to product design.

Fast forward to 1990s. Computer software starts to become mainstream. No longer the realm of the most technical users, human capabilities and product design started to clash again. Building on what the Human Factors researchers had learned, the science of usability engineering took off to meet the challenges of software design.

Some of the important human characteristics that must be considered include:

  • People have limited working memory capacities
  • Attention limits the ability of our minds to process only so many thoughts and inputs at once
  • Our eyes are drawn to salient features
  • We mentally group things in predictable ways
  • Our perceptions are colored by our experience and expectations

So how do you use this knowledge to make digital products that don’t give people fits? I’ll give you a hint: you’ll have to do a little more than add a line that “the application will be designed with usability in mind” to your requirements doc.

User-centered design is an approach to designing and developing software that results in applications and websites that are easier to use and better meet the needs of users.

What Is User-Centered Design

It starts by putting users at the forefront of design decision making. That’s what user-centered design is all about. Through research, observation, iterative design, and usability testing, we can understand the needs and behaviors of our users and use our expertise as designers to craft products which are useful, usable, and pleasurable to the users.

A typical user-centered design process would go something like this:

Shaun Article 4





  1. Analysis – Identify the characteristics of the users, user goals, context of use, and business goals. Talk to actual users and business stakeholders.
  2. Design – Create mockups or lo-fi, low cost prototypes of the solution based on the information gathered in the analysis phase.
  3. Testing – Test your mockups or prototypes with actual users to determine what works and what needs to be improved. Iterate on the design and testing phases to improve the process and move closer to …
  4. Development and Delivery – Building as you iterate through the test and design phase, you’ll approach higher fidelity until you’re ready to complete the development and delivery of your project.
  5. Evaluation and Lifecycle Management – Evaluate the success of the project against the characteristics defined in step 1 by measuring the behavior of actual users. Continue to ensure the product is updated using user-centered principles throughout the lifecycle.

Noticing a theme?

Why Is That So Important?

In the realm of ecommerce, the consultants User Interface Engineering used user testing to discover a usability flaw that was costing a major retailer $300M in lost revenue ( When designing products, Jakob Nielsen estimates that spending 10% of a project’s budget on usability doubles the quality metrics for the project (

When designing intranets and enterprise applications for internal use, your users may not have somewhere else to turn. In those cases, you don’t have to worry about losing customers. But poorly designed applications can cause all sorts of problems.

  • Employees are less efficient at their jobs when the tools they need are hard to use.
  • Confusing interfaces may cause employees to make costly errors.
  • Users blame themselves when they have trouble using an application, so having to spend the day using a suite of poorly designed applications leads to unhappy workers and lowered employee morale.

But We Don’t Have Designers! How Can I Get Me Some Of That User-Centered Design?

While you may not have designers, someone does design every application. It may be a business analyst or product manager doing mockups in Visio or it might be the developer turning user stories directly into front-end code. Inadvertent design is still design.

You don’t have to bring in an expensive agency or hire a team of User Experience Designers when you’re just starting out. The best way to improve the user experience of your products is simply to watch your users use your product.

User Interface Engineering has a list of excellent ways to start your user research (

Further Reading

If you’re interested in learning more, I suggest starting with the following books:

  • Don’t Make Me Think by Steve Krug – The classic introduction to designing websites and applications for usability. Quick and easy to read, it’s a must read for anybody involved in product work.
  • The Design of Everyday Things by Donald Norman – Norman is a pre-eminent cognitive psychologist and designer. Norman goes more in depth into the psychology of design than Krug, but this book is still quite accessible.
Tools Uncategorized

It’s Time to Stop the PDF Madness

Often, the quickest way to get a document deployed is to write it in a Word doc, create a PDF, and post it somewhere for users to access. This happens a lot for both end user and developer documentation. So why, then, is distributing PDF files for online reading a top web usability gaffe?


How’s Your API Documentation?

Trove ran a survey on Hacker News recently asking developers about their biggest pain points for API integration. While OAuth and backwards incompatible changes got their fair share of vitriol, I bet you can guess what the top source of frustration was.


Head over to the survey results, and scroll down to question 6 to see what developers hate about your API. Then ask yourself if maybe your API documentation needs a little help.

Language ROI Uncategorized Writing

What is Bad Spelling Costing You?

According to an article making the rounds last week from the good ol’ beeb: Spelling mistakes ‘cost millions’ in lost online sales:

He says he measured the revenue per visitor to the website and found that the revenue was twice as high after an error was corrected.


GarageBand and Enterprise App Documentation

My new iPad 2 finally arrived over the weekend. It’s a pretty great device and I’ve been enjoying exploring all of the cool things you can do with it and all of the great apps available. One of the things that sold me on the iPad over an Android tablet was the new GarageBand app. I’m an extremely poor guitar player and have a little experience running a sound board from my days at WKCO, so I thought dabbling in songwriting would be a lot of fun.

As a technical communicator, I’m interested in the evolution of user assistance from the days of Big Tomes for PC Applications to modern apps running on smartphones and tablets. The prevailing wisdom seems to be that a well-designed, intuitive user experience and excellent copywriting on labels and controls obviates the need for formal documentation. For many small apps, this works out just fine, especially for “fun” apps, where exploring the interface to learn how it works is part of the enjoyment.

Process Tools

Virtual Machine Love

As the project headed south in a hurry, a new wrinkle appeared, adding more stress to what was already a stressful situation. My trusty, three year old Windows XP desktop developed a bad case of the crashes. And of course, the crashes came at the most inopportune times: when editing a document to be delivered in minutes or when about to present on the WebEx. Clearly it was just time for a reformat, years of beta builds of software I’ve been documenting and wonky tools for one-off projects leaving their cruft like bad Windows applications are wont to do.

Business Process Writing

Going Agile with Technical Documentation

… we have come to value … working software over comprehensive documentation…

Agile Manifesto

We don’t do a lot of work with practitioners of agile methodologies. I think that’s partly because there’s some built-in hostility towards documentation in the values of agile development. Of course, while the Agile Manifesto is referring mostly to documentation for the front end of the cycle (i.e., the giant FRS), that hostility ends up spilling over to end-user documentation as well. (I don’t think that was the intention.)


On Technical Writing Resumes

The I’d Rather Be Writing techcom blog posts 10 Alternative Tests for Technical Writing Job Candidates. Not all of the ideas apply to our situation at STS, as we are all technical writers here, we don’t really have in-house documentation, and tend to recruit more entry-level folks who we can mold to our ways before they are corrupted by outside influences. However, there were some interesting suggestions.


White Space in Flare Searches

I’ve covered in the past some of Flare’s wonky behavior when it comes it to white space. I found another fun trick involving white space while searching in Flare 2.5 yesterday.