Kirkby Stephen

Last day of vacation up in the north of England staying with friends.

Portland to London

Sunny day for a flight out of Portland. Headed to London for three weeks.

Write the Docs: Adam DuVander – Docs as Marketing: Make Your API Irresistible

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

There are close to 9,000 APIs in the ProgrammableWeb directory. Just a while ago this was only a couple thousand. Even companies like Sears, USA Today and others have APIs.

Adam’s most popular tweet from last year was, “All your API documentation should get the same treatment and design as your marketing materials.” That was a quote from John Sheehan.

Adam’s talk was about the Three Cs: clarity, cost, and community.

By clarity of API docs Adam means that developers can actually find their way to the documentation portal. Not all companies have their API docs even remotely accessible. Clarity also means having a complete API reference available in a form that lets developers explore. A clear API also requires sample code. It’s best when it’s in a couple popular languages and can be plugged right in to a project. Decreasing the time to “Hello world” is key.

The cost of an API is also relevant. Developers need to know how much (if any) it costs to use a service and its API. Rate limits are another type of cost that needs to be clearly communicated. Google does this very well with their developer console. You can see usage and request higher limits right inline. Developers also need to find any API-specific terms of service.

For the community of an API Adam talked about needing a place where developers can discuss the API. A forum is a good start but a strong presence where your developers already are (e.g. StackOverflow) is better. Highlighting current work based on the API and focusing on changes coming to that API is another great way to build community. You also have to put a face to your API. Developers need to know who within the company they are or should be talking to.

Write the Docs: Ann Goliak – Helping the help pages

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Ann works at 37signals on their support team. She talked about the launch of their new customer-facing support documentation.

The help pages were designed to be self-service. The old layout organized things as a list of questions. There wasn’t any sense of hierarchy or importance to things. The first question listed was, “What are the ‘Your global feeds’ on the Dashboard?” So why was that the first question? Well, because it’d been clicked on the most times. It’s the most popular question because it’s the most popular question. Ultimately these question lists just didn’t make sense.

Mig Reyes and Ann worked on a new help site that, in short, would be browsable, intuitive, and reflect the actions and activity of users. It also needed to serve as a starting point for people to get up to speed with Basecamp. From the support team perspective they needed a landing page for resources, a flexible tool that provided for multiple ways of using a feature, and they needed a software platform that allowed for all of this to work well.

The new site combined a new CMS along with new help guides targeted toward specific use cases. It’s a cool combination of standalone guides with answers to common questions.

In writing the new docs the support team sought to be more concise in their writing. They also aimed for each doc to tell you specifically what you could do with the feature. Each answer in their FAQ section answers the question briefly while also providing a deep link in to documentation.

To edit content on the support site the team had to create a local development environment. They installed Xcode, Homebrew, git, generate an SSH key for Github, install Ruby, rebenv, bundler, pow, Jekyll, pull the repo from Github, and then bundle install and rake setup. It was that “simple.” They use this setup to stage changes to docs as well. By using git’s branches ability they can prep content before a release. Those same branches also allow for experimentation with the documentation.

In the first 2 months their support site saw 2,000 hits a day and support tickets were down 5% from with the previous system.

Write the Docs: Ashleigh Rentz – The technical challenges of serving docs at Google’s scale

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Ashleigh started at Google in 2004 as a data center hardware technician. In 2010 she got involved with a team of tech writers working on API documentation. The story she told was of how Google’s CMS came to be.

Google now has so many developer products it fills a periodic table. Literally. They made one.

Scaling problems can show up so gradually, you barely notice them until you’re already in big trouble. This happened for Google with their CMS. What worked in 2005 was horribly broken by 2010.

In 2005 Google had just hired Chris DiBona as the head of Open Source at Google. He started by focusing on getting Google to contribute more to Open Source projects. They created as a place for them to share code. When they launched this it was an introductory place to put some code. They started with documentation around their 10 APIs at the time. It’s build using EZT, or EaZy Templating. It’s a simple markup language you can use to define build objects in your documentation.

Google’s code site was optimized for small files, about 256K, and cached things in memory. This grew from Google’s issues scaling the hardware impacts of their consumption at the time. It was a time when a gigabyte of storage was still a lot.

In 2006 Google launched Project Hosting. In the days before Github this mean that they had a place to host and share open code projects.

By 2010 the builds for started running in to serious issues. New docs weren’t going live and they were hitting consistent errors. Files were taking almost 45 minutes to build. This meant that a tech writer working on a document had to give themselves a 45 minute lead time. A new project document set to launch at 2pm had to be filed at 1pm. Any typo or issue in the doc submitted meant another 45 minute delay. All of that was compounded by the fact that each build would fail with a typo in any new doc. One doc with an issue caused problems with new docs across all services.

There were other failures, too. Outside of writer mistakes they hit issues with disk I/O. This caused them to push the build cron jobs back to once every 2 hours. The fun part of that was that to pull any technical documentation down from the web also took 2 hours. Picture how awesome that is when you accidentally publish something. This 2 hour turn around time just didn’t work for how Google wanted to publish technical content.

They faced a choice between a band-aid fix and pushing the reset button on their CMS. They decided to develop a CMS that was actually meant for developer documentation. A team of people worked on this new site and the new CMS. The product of this was

Google’s new developer site as built differently. Gone were the days of having to do everything manually. Since Google now had App Engine they were able to leverage this as the platform from which they could build docs. Using Django nonrel so that they could work with the Django framework with the non-relational database structure of App Engine.

By moving the CMS away from EZT they avoided relying upon a site-wide build. Now they could build only what the writer asks for, when the writer asks for it. Syntax errors now returned in 60 seconds, not 60 minutes. And, your syntax errors don’t affect the system, just you. One downside to no site-wide builds is that when changes (for example, with pricing) happen outside the document tree Google has to manually rebuild the document to reflect the new pricing structure.

In late-2011 they started the process of migrating over to the new site. With 80,000 documents that’s a slow process. The problem is that it split their code documentation across 2 sites. It was a short-term issue that would eventually be fixed. The goal was to complete the move by May 2012 and all went smoothly.

Write the Docs: James Socol – UX and IA at Mozilla Support, and Helping 7.2 Million More People

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

James started things off after lunch. He works on and the Mozilla Developer Network.

James started talking with a short history of SUMO, which Michael talked a bit about yesterday. Through a series of redesigns they got to the design they now have. In that process they worked through solving the problems of earlier iterations.

When they tried solving this problem they lacked a good bit of data. What they did have, though, showed very low “helpful” scores on articles. They also had high exits from searches, re-searches, and high bounce rates.

One of the first things they did was have someone dedicated to the web side of support. They started with an heuristic evaluation and worked with a user experience expert on improving things. One thing they discovered in this was that if people got to the right article the helpfulness scores were very high. Outside of that, though, the scores tanked. They knew they had an information architecture problem.

They set out to analyze the current information architecture of the site. The first step was the manually look through the docs. They looked at what articles they had, where they were linked from, and the taxonomy that existed. To help with this they did a card sort, a means to guide users to generate a category tree.

With the map they had from the card sort they used Treejack and limited the user testing to just displaying the title of docs. The goal for users was then to say, “This is where I will find my answer.” With their current architecture of the time the success rates were as low as 1%. That’s bad. With that, though, they now had data. They had something they could work with and could optimize. What they found was interesting. Some articles were missing, some were badly named, and some had other issues.

Their user experience people had a few ideas. They proposed and tested a few solutions. This took their success rates in user tests up to highs of 92%. One task specifically went from a 1% success rate all the way up to 86%. With Treejack they were able to run all these tests by focusing just on the titles. It meant they could test quickly without having to rearrange or rewrite all of their docs.

At the end of things 10% more people were coming to the site and finding their answer. They tracked this by graphing the rate of “helpful” scores on documents. That 10% meant 7.25 million more people a year found the solution.

Write the Docs: Heidi Waterhouse – Search-first documentation: tags and keywords for frustrated users

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Heidi wrapped up talks just before lunch. She talked about search-first documentation and how search-first writing serves users. As she put it, lots of our users are coming to documentation angry. They have problems they need solved and can’t find the answers.

Heidi started in the mid-90s with table of contents focused documents. These are wonderful in that they’re orderly, linear, searchable, and often indexed. But, they are also rigid, linear, over-described, and leave users out of the process. They ignore the fact that a good document doesn’t just include everything in the world.

Mid-career she moved on to task-based documents. These are great in how they take in to account the goals of users. While they’re more modular they can be too chunky and hard to discover. There’s no path through these documents. You can hop from one task to another but the overall picture and flow becomes difficult. Task-based documents are also rigid about the information type they require.

More recently Heidi’s seen guerrilla documentation appearing. This is largely user-created, relevant to real needs, and may surprise you. The downside is that the documents can get stale, they’re uncontrolled, and they require leaving the ecosystem of the product. The signal to noise ratio can also be hard to determine.

Heidi’s proposal is that we take the best aspects of each of these models and create a new model. The model of search-first documentation. We’ll end up with something responsive to user needs. It will be documentation that is self-triaging and is born searchable. Ideally the terms used in this type of documentation comes from your users. It’s not important what you call a feature, it’s important what users call it and how they’ll search for it. For example, “blue screen of death” appears nowhere in Microsoft’s documentation but we all know what it means.

To make this type of documentation happen you first need to gather data. Using tech support, user communities, and Stack Overflow you can get all the info you need. Second, you’ll have to write the docs and keep publishing all the time. Writing pithy docs will help you focus on responding to a specific question. Plenty of these questions won’t be answered by a simple task.

Write the Docs: Jennifer Hartnett-Henderson – Sketchnotes: Communicate Complex Ideas Quickly

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Sketchnotes are a great way to communicate complex ideas very quickly. Mike Rohde defines sketchnotes as, “rich visual notes created from a mix of handwriting, drawings, hand-drawn typography, shapes and visual elements like arrows, boxes and lines.”

Jennifer’s been able to combine her art interests with her working career by perfecting how she does sketchnotes.

Sketchnotes work due to dual coding. If you combine the visual with the written it increases people’s ability to remember information. It’s important, though, to not think of sketchnotes as art. They’re not art and, instead, are a means of communication. They’re just notes. Sketchnotes are about combining shapes and lines in to a form that makes sense.

There are a few resources to help get up to speed with sketchnotes. Mike Rohde sells The Sketchnote Handbook. Eva-Lotta Lamm also publishes sketch notes from conferences all over. The tools you use aren’t as important as the practice. You can use digital or paper, it’s about what works best for you.