I finally got all packed and even cleared my inbox and task list. Ready for three weeks of vaca­tion now. London, Bath, Cambridge, the Lake District, and more are on the agenda.

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 direc­tory. Just a while ago this was only a cou­ple thou­sand. Even com­pa­nies like Sears, USA Today and oth­ers have APIs.

Adam’s most pop­u­lar tweet from last year was, “All your API doc­u­men­ta­tion should get the same treat­ment and design as your mar­ket­ing mate­ri­als.” That was a quote from John Sheehan.

Adam’s talk was about the Three Cs: clar­ity, cost, and community.

By clar­ity of API docs Adam means that devel­op­ers can actu­ally find their way to the doc­u­men­ta­tion por­tal. Not all com­pa­nies have their API docs even remotely acces­si­ble. Clarity also means hav­ing a com­plete API ref­er­ence avail­able in a form that lets devel­op­ers explore. A clear API also requires sam­ple code. It’s best when it’s in a cou­ple pop­u­lar lan­guages and can be plugged right in to a project. Decreasing the time to “Hello world” is key.

The cost of an API is also rel­e­vant. Developers need to know how much (if any) it costs to use a ser­vice and its API. Rate lim­its are another type of cost that needs to be clearly com­mu­ni­cated. Google does this very well with their devel­oper con­sole. You can see usage and request higher lim­its right inline. Developers also need to find any API-specific terms of service.

For the com­mu­nity of an API Adam talked about need­ing a place where devel­op­ers can dis­cuss the API. A forum is a good start but a strong pres­ence where your devel­op­ers already are (e.g. StackOverflow) is bet­ter. Highlighting cur­rent work based on the API and focus­ing on changes com­ing to that API is another great way to build com­mu­nity. You also have to put a face to your API. Developers need to know who within the com­pany they are or should be talk­ing 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 sup­port team. She talked about the launch of their new customer-facing sup­port documentation.

The help pages were designed to be self-service. The old lay­out orga­nized things as a list of ques­tions. There wasn’t any sense of hier­ar­chy or impor­tance to things. The first ques­tion listed was, “What are the ‘Your global feeds’ on the Dashboard?” So why was that the first ques­tion? Well, because it’d been clicked on the most times. It’s the most pop­u­lar ques­tion because it’s the most pop­u­lar ques­tion. Ultimately these ques­tion lists just didn’t make sense.

Mig Reyes and Ann worked on a new help site that, in short, would be brows­able, intu­itive, and reflect the actions and activ­ity of users. It also needed to serve as a start­ing point for peo­ple to get up to speed with Basecamp. From the sup­port team per­spec­tive they needed a land­ing page for resources, a flex­i­ble tool that pro­vided for mul­ti­ple ways of using a fea­ture, and they needed a soft­ware plat­form that allowed for all of this to work well.

The new site com­bined a new CMS along with new help guides tar­geted toward spe­cific use cases. It’s a cool com­bi­na­tion of stand­alone guides with answers to com­mon questions.

In writ­ing the new docs the sup­port team sought to be more con­cise in their writ­ing. They also aimed for each doc to tell you specif­i­cally what you could do with the fea­ture. Each answer in their FAQ sec­tion answers the ques­tion briefly while also pro­vid­ing a deep link in to documentation.

To edit con­tent on the sup­port site the team had to cre­ate a local devel­op­ment envi­ron­ment. They installed Xcode, Homebrew, git, gen­er­ate an SSH key for Github, install Ruby, rebenv, bundler, pow, Jekyll, pull the repo from Github, and then bun­dle install and rake setup. It was that “sim­ple.” They use this setup to stage changes to docs as well. By using git’s branches abil­ity they can prep con­tent before a release. Those same branches also allow for exper­i­men­ta­tion with the documentation.

In the first 2 months their sup­port site saw 2,000 hits a day and sup­port tick­ets were down 5% from with the pre­vi­ous 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 cen­ter hard­ware tech­ni­cian. In 2010 she got involved with a team of tech writ­ers work­ing on API doc­u­men­ta­tion. The story she told was of how Google’s CMS came to be.

Google now has so many devel­oper prod­ucts it fills a peri­odic table. Literally. They made one.

Scaling prob­lems can show up so grad­u­ally, you barely notice them until you’re already in big trou­ble. This hap­pened for Google with their CMS. What worked in 2005 was hor­ri­bly bro­ken by 2010.

In 2005 Google had just hired Chris DiBona as the head of Open Source at Google. He started by focus­ing on get­ting Google to con­tribute more to Open Source projects. They cre­ated code.google.com as a place for them to share code. When they launched this it was an intro­duc­tory place to put some code. They started with doc­u­men­ta­tion around their 10 APIs at the time. It’s build using EZT, or EaZy Templating. It’s a sim­ple markup lan­guage you can use to define build objects in your documentation.

Google’s code site was opti­mized for small files, about 256K, and cached things in mem­ory. This grew from Google’s issues scal­ing the hard­ware impacts of their con­sump­tion at the time. It was a time when a giga­byte of stor­age 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 code.google.com started run­ning in to seri­ous issues. New docs weren’t going live and they were hit­ting con­sis­tent errors. Files were tak­ing almost 45 min­utes to build. This meant that a tech writer work­ing on a doc­u­ment had to give them­selves a 45 minute lead time. A new project doc­u­ment set to launch at 2pm had to be filed at 1pm. Any typo or issue in the doc sub­mit­ted meant another 45 minute delay. All of that was com­pounded by the fact that each build would fail with a typo in any new doc. One doc with an issue caused prob­lems with new docs across all services.

There were other fail­ures, too. Outside of writer mis­takes 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 tech­ni­cal doc­u­men­ta­tion down from the web also took 2 hours. Picture how awe­some that is when you acci­den­tally pub­lish some­thing. This 2 hour turn around time just didn’t work for how Google wanted to pub­lish tech­ni­cal content.

They faced a choice between a band-aid fix and push­ing the reset but­ton on their CMS. They decided to develop a CMS that was actu­ally meant for devel­oper doc­u­men­ta­tion. A team of peo­ple worked on this new site and the new CMS. The prod­uct of this was developers.google.com.

Google’s new devel­oper site as built dif­fer­ently. Gone were the days of hav­ing to do every­thing man­u­ally. Since Google now had App Engine they were able to lever­age this as the plat­form from which they could build docs. Using Django non­rel so that they could work with the Django frame­work with the non-relational data­base struc­ture of App Engine.

By mov­ing the CMS away from EZT they avoided rely­ing 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 sec­onds, not 60 min­utes. And, your syn­tax errors don’t affect the sys­tem, just you. One down­side to no site-wide builds is that when changes (for exam­ple, with pric­ing) hap­pen out­side the doc­u­ment tree Google has to man­u­ally rebuild the doc­u­ment to reflect the new pric­ing structure.

In late-2011 they started the process of migrat­ing over to the new site. With 80,000 doc­u­ments that’s a slow process. The prob­lem is that it split their code doc­u­men­ta­tion across 2 sites. It was a short-term issue that would even­tu­ally be fixed. The goal was to com­plete 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 support.mozilla.org and the Mozilla Developer Network.

James started talk­ing with a short his­tory of SUMO, which Michael talked a bit about yes­ter­day. Through a series of redesigns they got to the design they now have. In that process they worked through solv­ing the prob­lems of ear­lier iterations.

When they tried solv­ing this prob­lem they lacked a good bit of data. What they did have, though, showed very low “help­ful” scores on arti­cles. They also had high exits from searches, re-searches, and high bounce rates.

One of the first things they did was have some­one ded­i­cated to the web side of sup­port. They started with an heuris­tic eval­u­a­tion and worked with a user expe­ri­ence expert on improv­ing things. One thing they dis­cov­ered in this was that if peo­ple got to the right arti­cle the help­ful­ness scores were very high. Outside of that, though, the scores tanked. They knew they had an infor­ma­tion archi­tec­ture problem.

They set out to ana­lyze the cur­rent infor­ma­tion archi­tec­ture of the site. The first step was the man­u­ally look through the docs. They looked at what arti­cles they had, where they were linked from, and the tax­on­omy that existed. To help with this they did a card sort, a means to guide users to gen­er­ate a cat­e­gory tree.

With the map they had from the card sort they used Treejack and lim­ited the user test­ing to just dis­play­ing the title of docs. The goal for users was then to say, “This is where I will find my answer.” With their cur­rent archi­tec­ture of the time the suc­cess rates were as low as 1%. That’s bad. With that, though, they now had data. They had some­thing they could work with and could opti­mize. What they found was inter­est­ing. Some arti­cles were miss­ing, some were badly named, and some had other issues.

Their user expe­ri­ence peo­ple had a few ideas. They pro­posed and tested a few solu­tions. This took their suc­cess rates in user tests up to highs of 92%. One task specif­i­cally went from a 1% suc­cess rate all the way up to 86%. With Treejack they were able to run all these tests by focus­ing just on the titles. It meant they could test quickly with­out hav­ing to rearrange or rewrite all of their docs.

At the end of things 10% more peo­ple were com­ing to the site and find­ing their answer. They tracked this by graph­ing the rate of “help­ful” scores on doc­u­ments. That 10% meant 7.25 mil­lion more peo­ple a year found the solution.