Write the API docs before the API exists¶
Description
This talk proposes to discuss a recent experiment we at Onfido undertook which took a novel approach: "write the docs before the API exists".
When I first got into software technical writing, I used to think that you should include technical writers from the start of a project. That's still a common approach, but as I personally became a more experienced writer, I began to find that projects very often changed—as they should, by design, in Agile development. The upshot of that for me personally, unfortunately, was that much of my work on documentation ended up being "sunk costs".
When drawing up our newest API at Onfido, I (by now a "quite technical" technical writer) set out with a backend engineer to not only document it from the start, but to actually assist in designing it—based on how I envisaged our customers would review the documentation, test the API, and interact with it.
This talk will discuss the lessons we learned along the way, how well the experiment worked, and more widely about how software technical writers can bring unique expertise to not only write about, but help shape the direction of projects and create the best possible developer experience.
- Conference: Write the Docs PRAGUE
- Year: 2019
