Your API Needs Technical Writers by Jennifer Rondeau

Transcript

1. Your API Needs Technical Writers Jennifer Rondeau, Capital One jennifer.rondeau@gmail.com @bradamante yourmom.io
2. API Documentation • Everybody agrees, we need docs. • Docs need to be good. • From there, it’s turtles all the way down … and down … Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
3. Jennifer Rondeau | writethedocsPDX
5. We Agree About The What • Mostly, anyway • But … • The who, the how, the when … not so much Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
6. Let’s Integrate Docs! • Nobody disagrees, exactly, but … • How? The details: o Work from spec at design phase o Work from spec out of code o Integrate with tests • FIRST: move away from “handoff” model o Help solve the “who?” and the “when?” Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
7. Let’s Integrate Docs!
8. Things That Help • The right doc platform • Teach your programmers to write • But it’s not enough … Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
9. Surely That’s Enough? • Maybe not • Assumptions o The right people to document a thing are the people who made it o Writing is fundamentally easy o Just need easier tools o Just need better instruction • Documentation is separate from product Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
10. What Helps the Most
11. Your API Needs a Writer
12. Writers Tell Stories • We provide the human element • Design needs the human element, too • Making the connections between APIs and their customers • “Writing code is one thing, writing docs is another.” Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
13. Well, Yes and No • Design first -> code + docs • Writers for: o Naming o Taxonomy/Ontology o Error messaging Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
14. Writers communicate! • Helping bridge the gap o Between internal and external o Between your API and your (external) customers Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
15. What About The How? • Not just about tools and training • More about the right roles • A dedicated seat at the table Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
16. Some Details • Writers are one of your most important evangelism/advocacy resources • Onboarding • API Questions! Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
17. Moar Writer Involvement Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante Better Docs AND API Moar successful API
18. Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante APIs are for communication This is what writers do THANK YOU!