Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Your API Needs Technical Writers by Jennifer Rondeau

Your API Needs Technical Writers by Jennifer Rondeau

More Decks by API Strategy & Practice Conference

Other Decks in Technology

Transcript

  1. 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
  2. We Agree About The What • Mostly, anyway • But

    … • The who, the how, the when … not so much Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
  3. 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
  4. Things That Help • The right doc platform • Teach

    your programmers to write • But it’s not enough … Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
  5. 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
  6. 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
  7. Well, Yes and No • Design first -> code +

    docs • Writers for: o Naming o Taxonomy/Ontology o Error messaging Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
  8. 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
  9. 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
  10. Some Details • Writers are one of your most important

    evangelism/advocacy resources • Onboarding • API Questions! Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante
  11. Moar Writer Involvement Jennifer Rondeau | APIStrat Austin, 2015 |

    @bradamante Better Docs AND API Moar successful API
  12. Jennifer Rondeau | APIStrat Austin, 2015 | @bradamante APIs are

    for communication This is what writers do THANK YOU!