From API Description to Developer Site: The hard part is working with people
•
2 j'aime•317 vues
API Descriptions can be powerful design and implementation tools. In this session, we look at approaches to using API descriptions to create excellent API documentation, what kind of challenges you might encounter (technical as well as political), and some strategies to solve them. We'll talk about tools and formats, as well as how to generate the best content with the least maintenance.
Recommandé
Recommandé
Contenu connexe
Tendances
Tendances (14)
Similaire à From API Description to Developer Site: The hard part is working with people
Similaire à From API Description to Developer Site: The hard part is working with people (20)
Dernier
Dernier (20)
From API Description to Developer Site: The hard part is working with people
- 1. © Avalara The hard part is working with people From API Description to Developer Site Anya Stettler API Strat 2015
- 2. Making sales tax less taxing 2CONFIDENTIAL & PROPRIETARY |
- 3. Making sales tax less taxing 3CONFIDENTIAL & PROPRIETARY |
- 4. Making sales tax less taxing 4CONFIDENTIAL & PROPRIETARY | https://stripe.com/docs/api#charges
- 5. Making sales tax less taxing 5CONFIDENTIAL & PROPRIETARY | Policy AND Technology
- 6. Making sales tax less taxing 6CONFIDENTIAL & PROPRIETARY |
- 7. Making sales tax less taxing 7CONFIDENTIAL & PROPRIETARY | …/v2/users Vs …/2.0/users Consistency is key
- 8. Making sales tax less taxing 8CONFIDENTIAL & PROPRIETARY | Not everything is worth fighting about
- 9. Making sales tax less taxing 9CONFIDENTIAL & PROPRIETARY | Central dictionary for shared vocabulary We all need to speak the same langauge
- 10. Making sales tax less taxing 10CONFIDENTIAL & PROPRIETARY | Rules can’t stand alone
- 11. Making sales tax less taxing 11CONFIDENTIAL & PROPRIETARY | More tools, less governance!
- 12. Making sales tax less taxing 12CONFIDENTIAL & PROPRIETARY | Make the right way the easiest way
- 13. Making sales tax less taxing 13CONFIDENTIAL & PROPRIETARY | draft standards draft standards ... in committee create tools management management management enforcement tool maintenance time saved through automation
- 14. Making sales tax less taxing 14CONFIDENTIAL & PROPRIETARY | https://github.com/paypal/api-standards/blob/master/api-style-guide.md
- 15. Making sales tax less taxing 15CONFIDENTIAL & PROPRIETARY | Franchise! -‐ Value input -‐ Pilot program -‐ Transparent feedback
- 16. Making sales tax less taxing 16CONFIDENTIAL & PROPRIETARY | Guide lines road
- 17. Making sales tax less taxing 17CONFIDENTIAL & PROPRIETARY |
- 18. Making sales tax less taxing 18CONFIDENTIAL & PROPRIETARY | http://swagger.io/
- 19. Making sales tax less taxing 19CONFIDENTIAL & PROPRIETARY | ?
- 20. Making sales tax less taxing 20CONFIDENTIAL & PROPRIETARY | Is it valid Swagger? YES NO
- 21. Making sales tax less taxing 21CONFIDENTIAL & PROPRIETARY | Vendor headers
- 22. Making sales tax less taxing 22CONFIDENTIAL & PROPRIETARY | A single “source of truth” definition Makes it easy for technical writers
- 23. Making sales tax less taxing 23CONFIDENTIAL & PROPRIETARY | Swagger accurately reflects API?
- 24. Making sales tax less taxing 24CONFIDENTIAL & PROPRIETARY | Follows company style guide?
- 25. Making sales tax less taxing 25CONFIDENTIAL & PROPRIETARY |
- 26. Making sales tax less taxing 26CONFIDENTIAL & PROPRIETARY | We still need people! • Human-‐readable property definitions • Define business flows • Describe best practices
- 27. Making sales tax less taxing 27CONFIDENTIAL & PROPRIETARY |
- 28. Making sales tax less taxing 28CONFIDENTIAL & PROPRIETARY |
- 29. Making sales tax less taxing 29CONFIDENTIAL & PROPRIETARY | 2. https://upload.wikimedia.org/wikipedia/commons/a/af/Bedarra_Island_aerial.jpg 3. https://upload.wikimedia.org/wikipedia/commons/7/7e/Palau_archipelago.jpg 5. https://pixabay.com/p-35105/ 7. https://www.flickr.com/photos/nelsonminar/286841113 8. https://upload.wikimedia.org/wikipedia/commons/e/eb/Bicycle_shed.JPG 10. https://commons.wikimedia.org/wiki/File:United_States_Code_Law_Book_Boston_Public_Library_6D2B1951.jpg 11. https://www.flickr.com/photos/dominicotine/7696681446 12. https://c1.staticflickr.com/5/4005/4698911975_c6b0accabd_b.jpg 15. https://commons.wikimedia.org/wiki/File:Dog_dressed_in_an_airplane_outfit.jpg http://ichef-1.bbci.co.uk/news/640/media/images/67206000/jpg/_67206577_de25.jpg 16. http://s3.freefoto.com/images/21/11/21_11_7_web.jpg 19. https://c2.staticflickr.com/4/3220/2936038678_06ae77a09d.jpg https://www.flickr.com/photos/dapuglet/8479185386 https://c1.staticflickr.com/3/2792/4195466130_cdccf7f7c3_b.jpg https://c1.staticflickr.com/3/2819/9190710208_cd972cd9c1.jpg https://c1.staticflickr.com/1/2/1616041_2f42627c7b.jpg https://pixabay.com/p-309065/ 20. https://www.flickr.com/photos/mbtrama/325408685 https://www.flickr.com/photos/8113246@N02/8203258965 23. https://www.flickr.com/photos/jurvetson/6877434491 25. 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.jpg 26. https://upload.wikimedia.org/wikipedia/commons/thumb/e/e7/Quill_(PSF)_vector.svg/2000px- Quill_(PSF)_vector.svg.png 27. https://www.flickr.com/photos/portland_mike/969236814 Image Credits
- 30. Making sales tax less taxing 30CONFIDENTIAL & PROPRIETARY | Thanks! Anya Stettler Product Manager, API Avalara anyarms anya.stettler@avalara.com