Write the Docs: Christopher Kelleher — Make Music Not Noise

I’m at Write the Docs today in Port­land 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.

Christo­pher wrapped up the first group of talks before the morn­ing break. His first boss taught him that mak­ing sound is not the same as mak­ing sense. That con­cept evolved in his mind to, infor­ma­tion is not the same as com­mu­ni­ca­tion. The stan­dards of music can guide us here.

Since that talk with his first boss Christo­pher has worked on dozens of types of docs. The metaphor or infor­ma­tion and com­mu­ni­ca­tion has helped him throughout.

The music world defines noise as sound with­out struc­ture. When you take sound and place it within a sat­is­fy­ing struc­ture you get music. The search for this sat­is­fy­ing struc­ture is innate. When placed in an MRI and given unfa­mil­iar music the intel­lec­tual cen­ters of people’s brain light up. They imme­di­ately try to make sense of the sound and deter­mine its patterns.

With doc­u­men­ta­tion we tend to accept docs that are fail­ures in the same way as unguided and unstruc­tured noise. But we lack the same fun­da­men­tal cog­ni­tive abil­i­ties to iden­tify them. When a doc­u­ment doesn’t com­mu­ni­cate it fails. Just like when sound doesn’t exist within a sat­is­fy­ing struc­ture. The like­li­hood that a doc­u­ment with­out com­mu­ni­ca­tion con­veys knowl­edge is extremely low. Ask your­self whether the doc you’re cre­at­ing con­tains the nec­es­sary information.

Next Christo­pher talked about delib­er­ate noise. Many times noise is acci­den­tal, but some­times it serves a pur­pose. The most com­mon lie on the inter­net is, “I have read and agreed to the terms of ser­vice.” No mean­ing­ful attempt at com­mu­ni­ca­tion resem­bles a terms of ser­vice. iTunes, for exam­ple, has a 29 page long terms of service.

It’s goal is not com­mu­ni­ca­tion. It’s goal is to pro­tect the legal inter­ests of Apple and to force you to click “I agree” with­out read­ing. This is often what noise in doc­u­ments does; it gets you to acquiesce.

Delib­er­ate noise comes in to play fre­quently in the legal and gov­ern­ment are­nas. Doc­u­men­ta­tion noise is treated as unavoid­able. But we totally can avoid it! A musi­cal doc­u­ment suc­ceeds by feed­ing your brain what it craves; it sat­is­fies the innate needs. This music-like sat­is­fac­tion is more than a nice-to-have, it’s essential.

Write the Docs: James Pearson — Don’t Write Documentation

I’m at Write the Docs today in Port­land 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 isn’t a writer by trade but is rather a sys­tem admin­is­tra­tor. For him doc­u­men­ta­tion is a way of ensur­ing that every­thing works and our users are happy. He works at iFixIt where they teach every­one to repair the prod­ucts they use every day. The doc­u­men­ta­tion on iFixIt’s site is all wiki-based and very graphics-heavy. About half the guides are user-contributed.

As James said, good documentation’s worst enemy is bad doc­u­men­ta­tion. Not every­one loves writ­ing doc­u­men­ta­tion and when the love isn’t there the qual­ity can suf­fer. There’s some­thing dif­fer­ent in our brains about docs. We don’t treat them like soft­ware and, as a cul­ture, are some­times numb to doc­u­men­ta­tion. We assume it’s bad and avoid read­ing it. If we can focus on increas­ing the qual­ity of docs we can com­bat this numb­ing effect.

When you allow bad doc­u­men­ta­tion to linger it drags the qual­ity of the over­all library down. A sim­i­lar effect to the bro­ken win­dows the­ory. Bad doc­u­men­ta­tions allows for peo­ple to inter­nal­ize the notion that it’s okay to have crappy doc­u­men­ta­tion. That’s not what we want; we want high stan­dards for qual­ity. As an aside, out­dated docs fall in to this bucket as well. Updat­ing them is fre­quently an easy thing to fix.

The first cat­e­gory that James really, really hates are auto-generated docs. There are three great virtues of a pro­gram­mer: lazi­ness, impa­tience, and hubris. Lazi­ness is what dri­ves us to cre­ate auto-generated docs. Fre­quently the result is not worth­while, not in-depth, and not reviewed with an eye toward user-facing clar­ity. Javadoc may be a good tool but it’s gone bad. Just because you can do some­thing with a tool doesn’t mean you should. Com­put­ers, at their core, suck at writ­ing docs for humans to read.

James then cov­ered the sec­ond cat­e­gory of bad docs, those that use overly ver­bose lan­guage. By know­ing your audi­ence you can find places to omit need­less words. One audi­ence may require great detail while another can do with just an overview. ssh allows for 4 lev­els of ver­bosity within the tool itself. What James seeks is a doc­u­men­ta­tion equiv­a­lent of that.

The final thing James talked about was mistake-proofing. Humans will always make mis­takes, but mis­takes don’t always need to become defects in the final prod­uct. An engi­neer at Toy­ota came up with the con­cept of delib­er­ately design­ing mis­takes in to your prod­uct cre­ation process. The trick is to fix these prod­uct fail­ures rather than doc­u­ment­ing around them.

After the talk James posted his slides. Check them out.

Write the Docs: Susan Salituro — From docs to engineering and back again

I’m at Write the Docs today in Port­land 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.

Susan is a soft­ware engi­neer at Pixar and has also had a long career as a tech­ni­cal writer. She was inspired by last year’s con­fer­ence and the talks that came out of it.

Her talk is about a story, a jour­ney of career choices and being open to oppor­tu­nity. She quoted Tom Fre­ston who said, “A career path is rarely a path at all. A more inter­est­ing life is usu­ally a more crooked, wind­ing path of mis­steps, luck, and vig­or­ous work.”

In col­lege Susan wasn’t sure what she wanted to do. She love astron­omy, though, and wanted to be an astro­physi­cist; the prob­lem was that she didn’t truly believe she could fin­ish a physics major. That dream was scratched. She had half the cred­its toward a math major, though, and pur­sued that. That switch left her with some free time which she devoted to Eng­lish literature.

That com­bi­na­tion led her to take a tech­ni­cal writ­ing course. It opened up her eyes to the pro­fes­sion of tech­ni­cal writ­ing. At the time she felt that was where she was des­tined to go. For a few years she fol­lowed that path. The com­mu­nity, con­fer­ences, pas­sion, learn­ing, flex­i­bil­ity all drew her to the indus­try. Susan enjoyed learn­ing what cus­tomers did with a prod­uct. It was about the cus­tomer and mak­ing their lives eas­ier. But, she started to won­der if there was some­thing more, some­thing deeper.

That led her to dig in to what she found inter­est­ing in tech­ni­cal writ­ing and where her pas­sion lay within that. Susan got really in to what made soft­ware tick. She’d spent so long under­stand­ing how pro­grams worked from a user stand­point. Now she started learn­ing more pro­gram­ming and dig­ging in behind the scenes. She spent the next few years doing API tech­ni­cal writing.

Then, she made her way to Pixar. The man­ager there wanted to use DITA for a new project. Through that she got the chance to learn Python to write doc scripts and make to exe­cute those scripts. While she never thought of her­self as a pro­gram­mer she had accu­mu­lated enough skill to enter that world and make pro­gram­ming her own.

The next chal­lenge came in mov­ing to the soft­ware release engi­neer­ing team at Pixar. This pushed her to an even steeper learn­ing curve where she was learn­ing Perl and deeper lev­els of Python. The com­mu­nity she’d found in tech­ni­cal writ­ing was still there, but it was mostly inter­nal to Pixar. The men­tor­ing and help came from inside the com­pany but Susan didn’t get the sense of a large exter­nal com­mu­nity around these skills. The flex­i­bil­ity she found in tech writ­ing also dimin­ished. On-call hours were expected and work came at all times.

After mov­ing to Canada, Susan changed com­pa­nies and shifted to an infor­ma­tion archi­tec­ture role at a smaller com­pany. She was now work­ing solo with­out a strong inter­nal com­mu­nity but was able to stretch her reach in to new roles that had thriv­ing exter­nal com­mu­ni­ties. Unfor­tu­nately the com­pany went bank­rupt and Susan went back to Pixar as a Soft­ware Infra­struc­ture Engineer.

On one level this new role meant reach­ing her goal of meld­ing doc­u­men­ta­tion and pro­gram­ming. They man­date was to find solu­tions for doc prob­lems and address tools and process issues. The focus was not just doc­u­men­ta­tion but the entire soft­ware life cycle. She worked on tools for the release engi­neer­ing team, the qual­ity assur­ance group, and more. At heart she still con­sid­ered her­self a tech­ni­cal writer.

Write the Docs: Drew Jaynes — Putting the (docs) Cart Before the (standards) Horse

I’m at Write the Docs today in Port­land 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.

Drew opened the sec­ond day of talks Tues­day. He works as a web engi­neer at 10up and con­tributes to the Word­Press project as well. His talk focused on Word­Press’ approach to inline documentation.

Up until about 8 months ago Word­Press paid very lit­tle atten­tion to the details of inline docs. There were more than 10 years of loosely fol­low­ing php­Doc 1.0. The codex, a wiki-based doc­u­men­ta­tion site, was still seen as the main entry point to learn­ing more.

This wasn’t work­ing any­more with hun­dreds of thou­sands lines of code. The codex had grown to 2,300+ pages of man­u­ally curated con­tent. That means each release saw the docs team man­u­ally going through the codex and try­ing to cre­ate pre-release mas­ter lists of required updates in the docs.

Enter hook docs. The docs team decided to cre­ate their own doc spec, largely inspired by exist­ing frame­works. They were expect­ing a large influx of con­trib­u­tors to docs and wanted to set a con­sis­tent base­line for new peo­ple to the project.

The evo­lu­tion of the docs team saw them estab­lish them­selves as a more offi­cial con­trib­u­tor group. They did an infor­mal sum­mit at the Open Help Con­fer­ence last sum­mer, ran a codex sur­vey to see how peo­ple used it, and devel­oped a roadmap for doc­u­men­ta­tion going for­ward. Never under­es­ti­mate the power of a docs team armed with a roadmap.

As soon as that roadmap was in place the docs team was off to the races. The top item was to burn the codex with the fire of a thou­sand suns; but first they needed some­thing to replace it. Work began on a parser and code ref­er­ence theme and hook docs began in earnest.

At this point the docs team has 3–5 sub teams con­tribut­ing to var­i­ous aspects of the docs roadmap. There are weekly chats and vir­tual sprints over the week­ends. Fur­ther­more, the col­lab­o­ra­tion with other teams has raised the pro­file of docs within the project. 8 months in to this project they’ve doc­u­mented every hook in the project, more than 2,200 of them. There was a 48% increase in inline doc­u­men­ta­tion over just 3 releases span­ning one year. Those same 3 releases saw 40 new con­trib­u­tors to docs.

The biggest dif­fer­ence is that there are now peo­ple pay­ing atten­tion to the details of doc­u­men­ta­tion. It ensures things are con­sis­tent, com­plete, and reviewed. Devel­op­ing that stan­dard for doc­u­men­ta­tion was immensely help­ful. Part of that was tak­ing the docs cre­ated over 10 years and devel­op­ing that stan­dard from the docs. In the long-term this allows them to adopt new aspects in to the spec with­out caus­ing vast dis­rup­tion each time.

Write the Docs: Christina Elmore — Death by Documentation

I’m at Write the Docs today in Port­land 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.

Christina wrapped up the first day of talks. She opened by say­ing how she regret­ted the title for her talk, because her think­ing has evolved.

She started her talk speak­ing about poor pre­sen­ta­tions. Most peo­ple blame Pow­er­Point for cre­at­ing bad pre­sen­ta­tions. What Christina believed, though, was that pre­sen­ta­tions were try­ing to doc­u­ment them­selves. This is what led to the wall of text on a slide. Peo­ple were con­flat­ing the goals of doc­u­men­ta­tion and presentation.

What’s the dif­fer­ence between the two? First, doc­u­men­ta­tion is self-guided and meant to be read. Pre­sen­ta­tions are presenter-guided and meant to be heard and watched. With these dif­fer­ences in place Christina pro­posed a prin­ci­ple, good pre­sen­ta­tion slides are bad doc­u­ments. The dif­fer­ences above are key and impor­tant. The way our brain processes the infor­ma­tion in each differently.

Peo­ple raise ques­tions about that prin­ci­ple, though.

  1. How will I remember?
  2. What will I share?
  3. What if I’m not there to explain it?

The first ques­tion gets at ques­tion­ing who really mat­ters. You, as the pre­sen­ter, are not who mat­ters. Your knowl­edge and mem­ory from the pre­sen­ta­tion are not cen­tral. Its that of the audi­ence. To remem­ber, cre­ate a story struc­ture. This ben­e­fits both your audi­ence and your work­ing mem­ory. Rehearse your pre­sen­ta­tion to cre­ate reten­tion. These both work for your audi­ence and you.

Matt Haughey’s guide to bet­ter pre­sen­ta­tions cov­ers the ques­tion. Ulti­mately the con­tent of your slides should not be the key thing you are try­ing to share. As Matt wrote,

The one thing you might notice in my advice and pre­vi­ous slides is that they don’t really make much sense out­side of my talk. I’m ok with that, since I hope peo­ple get to attend the talk or see video of the talk.

The third ques­tion asks if you should be cre­at­ing a doc­u­ment or a pre­sen­ta­tion. If you require those walls of text then per­haps the infor­ma­tion is not best explained in a pre­sen­ta­tion. Some­times the best deliv­er­able is not a slide but a report or a text-based document.

What’s at stake here is that our doc­u­ments suf­fer as well when we don’t under­stand the dif­fer­ence between doc­u­ments and pre­sen­ta­tions. To start you can, well, doc­u­ment the dif­fer­ence between these for­mats of infor­ma­tion. One way to look at this is to dis­tin­guish between a pre­sen­ta­tion and a con­ver­sa­tion. They aren’t the same thing.

Christina ended with a bold pro­posal: work to elim­i­nate the pre­sen­ta­tion within your orga­ni­za­tion. Ama­zon and LinkedIn have done this; they have meet­ings begin with 10 min­utes of silence where every­one reads over the same doc­u­ment. Then they dis­cuss things in a true con­ver­sa­tion. By doing this you can ensure pre­sen­ta­tions hap­pen only when nec­es­sary. You can then nur­ture a healthy cul­ture of presentation.

Write the Docs: Amelia Abreu — Data, Documentation and Memory

I’m at Write the Docs today in Port­land 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.

Amelia talked about some of the the­o­ries behind doc­u­men­ta­tion. She referred to it as a decid­edly non-practical talk. Amelia started as an archivist.

The first ques­tion she looked at is, what is it that we doc­u­ment? Part of what we do as doc­u­men­tar­i­ans is actu­ally look­ing for what is not doc­u­mented. At times that’s just as impor­tant as what is doc­u­mented. In her work as an archivist and ethno­g­ra­pher part of what Amelia did was look at that which hap­pened off the record. You explore those areas that are hid­den in the offi­cial record and poke at whether they can be defined.

Amelia then talked about move­ments dur­ing the early and mid-1900s in France. These were the com­mu­ni­ties that cre­ated micro­film and other stan­dards of archival even dur­ing the dis­rup­tion and oppres­sion of World War II. While we’re in a far dif­fer­ent cir­cum­stance than 1950s France we can still learn a lot from the work done dur­ing these peri­ods. Some of the French researchers believed that ship­ping micro­film copies of great works of text around the world would help lead toward global peace.

Meta­data is at the core of our insti­tu­tional knowl­edge. Amelia used the exam­ple of Ama­zon which sold books at close to cost as a means to gather knowl­edge about the shop­ping habits of afflu­ent customers.

As doc­u­men­tar­i­ans we are the providers of infor­ma­tion archi­tec­ture and infra­struc­ture. Think­ing about infra­struc­ture need not be lim­ited to human ver­sus tech­no­log­i­cal com­po­nents. It can also be thought of in terms of inter­re­lated social, orga­ni­za­tional, and tech­ni­cal com­po­nents or sys­tems. We also must rec­og­nize human work as infra­struc­ture. Infra­struc­tures are often used in such a way that exhausts the best inten­tions of those who cre­ated them. Doc­u­men­ta­tion is no excep­tion to this process.

Write the Docs: Maxwell Hoffmann — Say more with less: writing for a global audience

I’m at Write the Docs today in Port­land 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.

Maxwell works at Adobe as a prod­uct evan­ge­list. He’s spent 12 years in trans­la­tion and local­iza­tion with more than 20 years work­ing in tra­di­tional tech­ni­cal documentation.

We’ve come full cir­cle in terms of our hand-held devices. We’ve gone from cuneiform tablets to scrolls to desk­top com­put­ers and now back to hand-held smart­phones. This means our con­tent must be in shorter pieces, faster to load, and eas­ier to scan.

The biggest bar­rier to good trans­la­tion in Maxwell’s mind is poor Eng­lish. The more com­plex the lan­guage, the harder the trans­la­tion. Sim­pli­fy­ing your docs and your lan­guage sim­pli­fies your trans­la­tion. For hand-held devices this helps as sim­pli­fied Eng­lish by as much as 30%. We can all ben­e­fit from writ­ing sim­pli­fied English.

Maxwell cov­ered the 10 rules for writ­ing ASD-STE 100 sim­pli­fied Eng­lish. This has 10 key values:

  1. Write pos­i­tive statements.
  2. Write short sentences.
  3. Use one topic per sentence.
  4. Use valid nomenclature.
  5. Write sim­ple sentences.
  6. Use the active voice.
  7. Do not use gerunds (-ing words).
  8. Avoid con­di­tional tenses.
  9. Avoid word clusters.
  10. Use valid nomen­cla­ture & abbreviations.

To work on these rules try writ­ing an out­line on a type­writer. With this you can only write; there are no dis­trac­tions. There’s no edit­ing or for­mat­ting. You will feel and write dif­fer­ently. Or, if type­writ­ers aren’t you thing, you can break long sen­tence writ­ing pat­terns by dic­tat­ing your writing.

Write the Docs: Simeon Franklin & Marko Gargenta — TechDocs at Twitter: Creating the Culture of Documentation

I’m at Write the Docs today in Port­land 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.

Marko and Simeon both work at Twit­ter on doc­u­men­ta­tion projects. About 9 months ago Twit­ter acquired a soft­ware train­ing com­pany Marko and Simeon both worked at. The goal was to cre­ate Twit­ter Uni­ver­sity for inter­nal train­ing and learn­ing. It didn’t take long, though, for some­one to sug­gest they tackle the tech­ni­cal doc­u­men­ta­tion as well.

The tech­ni­cal doc­u­men­ta­tion they work on at Twit­ter is internal-facing. It’s engineer-to-engineer doc­u­men­ta­tion and not the pub­lic API specs. They ran a sur­vey about the inter­nal docs. Using the net pro­moter score stan­dard they found that most peo­ple hated the inter­nal docs. Some com­mon com­plaints were that the docs were incom­plete, dep­re­cated, non-existant, or unclear.

Their tech­ni­cal docs team was just 3 doc writ­ers. They view the team as the engi­neer­ing grease inter­nal to the com­pany. The goal is to make things run smoother. To do this they’re mak­ing docs like code. The process they’re work­ing toward is to code, test, doc, and then ship.

They’re tak­ing lessons from the test-driven-development shift to bring docs in to that process. Devel­op­ers at Twit­ter have got­ten accus­tomed to need­ing tests fin­ished before they com­mit code. The chal­lenge is to make that cul­tural assump­tion the same around docs.

The plan is three-pronged. The plat­form is DocBird, the pub­lish­ing plat­form. Above that lie self-service tools and tem­plates. Finally there’s Doc­Day, an inter­nal doc sprint that aims to pro­mote doc­u­men­ta­tion inter­nally. As they got started they real­ized there was no coher­ent plan or stan­dard to docs. Dif­fer­ent teams used dif­fer­ent tools, for­mats, and processes. Some teams were even using Google Docs. Their inter­nal wiki has more than 60,000 pages across more than 150 spaces.

In treat­ing their docs as code they’re check­ing the docs in to git, those docs are plain text, and they’re reg­u­larly reviewed and merged. This is where tech­nol­ogy comes in to the res­cue. They built a home­brew doc­u­men­ta­tion plat­form they call DocBird. They hit a few road­blocks in this process. The fact that DocBird is not a wiki, isn’t ReStruc­tured­Text, and isn’t gen­er­ated from the source code were all ini­tial problems.

Since the docs live in the code repo they’re able to track the amount docs drift away from code. The goal is to keep things in sync, but it’s a challenge.

The tem­plate layer of their project is aimed to enabling devel­op­ers to get to min­i­mum viable doc­u­men­ta­tion as fast as pos­si­ble. They’re work­ing to enforce con­sis­tency in doc­u­men­ta­tion through those same tem­plates; things like a sim­i­lar lan­guage are impor­tant here. It solves the prob­lem dis­cussed in an ear­lier talk about how intim­i­dat­ing a blank page is. By fill­ing some default lan­guage in to the tem­plate they help devel­op­ers get over that ini­tial hurdle.

In terms of cov­er­age the goal is to have 100% of known projects cov­ered with the same docs. They’re boot­strap­ping this by start­ing with readme files that point to all the docs that exist. They don’t all have to be in DocBird right away.

With only 3 peo­ple using resources well is key. They’re push­ing edu­ca­tion as a way to lever­age those three doc­u­men­tar­i­ans to have max­i­mum impact. By work­ing on tem­plates, for exam­ple, 3 doc­u­men­tar­i­ans can influ­ence hun­dreds of docs. Ulti­mately bet­ter tech­nol­ogy alone will not cre­ate a cul­ture of documentation.

The key prob­lem is get­ting Twitter’s thou­sand+ engi­neers to write docs. On the one hand they’re telling the engi­neers that a lack of docs should be con­sid­ered tech­ni­cal debt. On the other, though, they’re telling the engi­neers that if they want other teams to adopt their library they need to pack­age it attrac­tively; docs are a key part of that package.

Write the Docs: Kenneth Reitz — Documentation at Scale

I’m at Write the Docs today in Port­land 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.

Ken­neth wrapped up the set of talks before the after­noon break. He works for Heroko, a web appli­ca­tion deploy­ment com­pany. He’s also a mem­ber of the Python Soft­ware Foun­da­tion and an active mem­ber of the com­mu­nity. He seri­ously con­tributes to about 18 projects and has around 100 lit­tle experiments.

His talk focused on lan­guage, and how it works within doc­u­men­ta­tion. Spo­ken lan­guage is what allows us to express ideas to one another. Our writ­ten lan­guage abil­i­ties then allow for us to express those ideas over a his­tor­i­cal time scale. As we’ve devel­oped these skills the human hard­ware hasn’t changed, but the software’s been upgraded.

As we’ve evolved our abil­ity to com­mu­ni­cate with one another has expanded from one-to-one con­ver­sa­tions to one-to-many. The print­ing press, for one, gave the abil­ity for a sin­gle entity to com­mu­ni­cate to an extremely large mass of peo­ple. This con­tin­ued with news­pa­pers, books, tele­vi­sion, and radio. This formed the nar­ra­tive of “the public.”

The next step in com­mu­ni­ca­tion is many-to-many. This for­mat is inher­ent to the inter­net. If you have access to the inter­net you have access to a uni­verse of infor­ma­tion and ideas. The impli­ca­tions of this shift are huge.

Doc­u­men­ta­tion doesn’t have to be about a soft­ware work­flow or open source project – it can be used to con­vey ideas much larger than your­self. Its infor­ma­tion archi­tec­ture is inher­ent and a pow­er­ful tool for devel­op­ing ideas over time. Finally, it enables us to develop ideas on a longer time­line and with more peo­ple than we’d ever be able to do by ourselves.

Ken­neth works on The Hitchhiker’s Guide to Python, an open source project that’s out­line and curated through a com­bi­na­tion of Github and Read the Docs.

Write the Docs: Lois Patterson — What Makes Good API Documentation: An Example-Based Approach

I’m at Write the Docs today in Port­land 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.

Lois got inter­ested in this sub­ject through work­ing on an API prod­uct she had to doc­u­ment. The com­pany she works for has a very com­plex project that they were build­ing an API for. They saw the API as a means for let­ting devel­op­ers to nar­row the scope of func­tion­al­ity avail­able to cer­tain user bases.

To start on this project Lois researched other good API doc sets on the web. What she found was that if you have a good API the docs are quite likely to be good as well. Twit­ter, Github, Face­book, and Flickr were cited as exam­ples here. Why are these good APIs? First, they seg­ment doc­u­men­ta­tion in to buck­ets. Twit­ter has API doc­u­men­ta­tion bro­ken in to tweet, user, and other spe­cific aspects. Sim­i­larly Flickr’s API Gar­den gives you con­crete exam­ples of how other devel­op­ers have used the API.

While there aren’t inher­ent API stan­dards those APIs which become extremely pop­u­lar become de facto stan­dards. The Pro­gram­ma­bleWeb ser­vice is a good resource for search­ing through var­i­ous pub­lic web APIs.

Swag­ger and Atlassian’s REST browser are handy tools for explor­ing and test­ing the con­tent within an API.

Lois argued that any good API doc­u­men­ta­tion should have good descrip­tions, tuto­ri­als, code exam­ples (both snip­pets and work­ing apps), a sand­box test envi­ron­ment, as well as FAQs. At Lois’ com­pany some­one tried to argue that code exam­ples weren’t needed because, “any good devel­oper can fig­ure out how to make a work­ing appli­ca­tion.” While they may be tech­ni­cally able to fig­ure it out the job of your API docs is to make that process eas­ier. Clear ver­sion­ing for the API as well as sug­ges­tions on using the API are also helpful.

A first pass on API docs can be as sim­ple as tak­ing the spec and turn­ing it in to a user-facing doc. Tak­ing that to the devel­op­ers then gives you feed­back to go from and get a set of points to clarify.