©  Avalara

Translating  and  Testing  your  documentation

From  API  Description  to  Developer  Site

Anya  StettlerDefrag  2015

Making  sales  tax  less  taxing 2CONFIDENTIAL   &  PROPRIETARY      |

Making  sales  tax  less  taxing 3CONFIDENTIAL   &  PROPRIETARY      |

Making  sales  tax  less  taxing 4CONFIDENTIAL   &  PROPRIETARY      |

https://stripe.com/docs/api#charges

Making  sales  tax  less  taxing 5CONFIDENTIAL   &  PROPRIETARY      |

Policy  AND  Technology

Making  sales  tax  less  taxing 6CONFIDENTIAL   &  PROPRIETARY      |

Making  sales  tax  less  taxing 7CONFIDENTIAL   &  PROPRIETARY      |

…/v2/users

Vs

…/2.0/users

Consistency  is  key

Making  sales  tax  less  taxing 8CONFIDENTIAL   &  PROPRIETARY      |

Not  everything  is  worth  fighting  about

Making  sales  tax  less  taxing 9CONFIDENTIAL   &  PROPRIETARY      |

Central  dictionary  for  shared  vocabulary

We  all  need  to  speak  the  same  langauge

Making  sales  tax  less  taxing 10CONFIDENTIAL   &  PROPRIETARY      |

Rules  can’t  stand  alone

Making  sales  tax  less  taxing 11CONFIDENTIAL   &  PROPRIETARY      |

More  tools,  less  governance!

Making  sales  tax  less  taxing 12CONFIDENTIAL   &  PROPRIETARY      |

The  right  way  should  be  easy

Making  sales  tax  less  taxing 13CONFIDENTIAL   &  PROPRIETARY      |

draft  standards

draft  standards

...  in  committee

create  tools

management

management

management

Nag  nag  nag...

tool  maintenance

time  saved  through  

automation

Making  sales  tax  less  taxing 14CONFIDENTIAL   &  PROPRIETARY      |

https://github.com/paypal/api-­standards/blob/master/api-­style-­guide.md

Making  sales  tax  less  taxing 15CONFIDENTIAL   &  PROPRIETARY      |

Franchise!

-­‐ Value  input

-­‐ Pilot  program

-­‐ Transparent  feedback

Making  sales  tax  less  taxing 16CONFIDENTIAL   &  PROPRIETARY      |

Guide  lines  road

Making  sales  tax  less  taxing 17CONFIDENTIAL   &  PROPRIETARY      |

Making  sales  tax  less  taxing 18CONFIDENTIAL   &  PROPRIETARY      |

http://swagger.io/

Making  sales  tax  less  taxing 19CONFIDENTIAL   &  PROPRIETARY      |

?

Making  sales  tax  less  taxing 20CONFIDENTIAL   &  PROPRIETARY      |

Is  it  valid  Swagger?

Making  sales  tax  less  taxing 21CONFIDENTIAL   &  PROPRIETARY      |

Vendor headers

Making  sales  tax  less  taxing 22CONFIDENTIAL   &  PROPRIETARY      |

A  single  “source  of  truth”  definition

Makes  it  easy  for  technical  writers

Making  sales  tax  less  taxing 23CONFIDENTIAL   &  PROPRIETARY      |

Swagger  accurately  reflects  API?

Making  sales  tax  less  taxing 24CONFIDENTIAL   &  PROPRIETARY      |

Follows  company  style  guide?

Making  sales  tax  less  taxing 25CONFIDENTIAL   &  PROPRIETARY      |

Making  sales  tax  less  taxing 26CONFIDENTIAL   &  PROPRIETARY      |

We  still  need  people!

• Human-­‐readable  property  definitions

• Define  business  flows

• Describe  best  practices

Making  sales  tax  less  taxing 27CONFIDENTIAL   &  PROPRIETARY      |

Making  sales  tax  less  taxing 28CONFIDENTIAL   &  PROPRIETARY      |

Making  sales  tax  less  taxing 29CONFIDENTIAL   &  PROPRIETARY      |

2.  https://upload.wikimedia.org/wikipedia/commons/a/af/Bedarra_Island_aerial.jpg3.  https://upload.wikimedia.org/wikipedia/commons/7/7e/Palau_archipelago.jpg5.  https://pixabay.com/p-­35105/7.  https://www.flickr.com/photos/nelsonminar/2868411138.  https://upload.wikimedia.org/wikipedia/commons/e/eb/Bicycle_shed.JPG10.  https://commons.wikimedia.org/wiki/File:United_States_Code_Law_Book_Boston_Public_Library_6D2B1951.jpg11.  https://www.flickr.com/photos/dominicotine/769668144612.  https://c1.staticflickr.com/3/2451/3704243811_55b45a0fd0_b.jpg15.  https://commons.wikimedia.org/wiki/File:Dog_dressed_in_an_airplane_outfit.jpghttp://ichef-­1.bbci.co.uk/news/640/media/images/67206000/jpg/_67206577_de25.jpg16.  http://s3.freefoto.com/images/21/11/21_11_7_web.jpg19.  https://c2.staticflickr.com/4/3220/2936038678_06ae77a09d.jpghttps://www.flickr.com/photos/dapuglet/8479185386https://c1.staticflickr.com/3/2792/4195466130_cdccf7f7c3_b.jpghttps://c1.staticflickr.com/3/2819/9190710208_cd972cd9c1.jpghttps://c1.staticflickr.com/1/2/1616041_2f42627c7b.jpghttps://pixabay.com/p-­309065/20.  https://www.flickr.com/photos/mbtrama/325408685https://www.flickr.com/photos/8113246@N02/820325896523.  https://www.flickr.com/photos/jurvetson/687743449125.  https://upload.wikimedia.org/wikipedia/commons/thumb/0/0b/Sandro_Botticelli_-­_La_nascita_di_Venere_-­_Google_Art_Project_-­_edited.jpg/1280px-­Sandro_Botticelli_-­_La_nascita_di_Venere_-­_Google_Art_Project_-­_edited.jpg26.  https://upload.wikimedia.org/wikipedia/commons/thumb/e/e7/Quill_(PSF)_vector.svg/2000px-­Quill_(PSF)_vector.svg.png27.  https://www.flickr.com/photos/portland_mike/969236814

Image  Credits

Making  sales  tax  less  taxing 30CONFIDENTIAL   &  PROPRIETARY      |

Thanks!

Anya  StettlerProduct  Manager,  APIAvalara

anyarms

anya.stettler@avalara.com