Steph Mills
Splunk
A Path Through the Woods: Defining and Documenting Top API Use Cases
Biography
Steph Mills is the owner of the Splunk Enterprise REST API docs, which contain manually generated information about hundreds of endpoints. She loves fantasy and science fiction, and fantasy and science fiction analogies. When not reading and writing, you can find her on a mountain trail or training Brazilian jiu-jitsu.
Talk description
Philip Pullman, author of The Golden Compass, describes a storytelling process in which authors guide readers along a metaphorical trail through the woods, never straying into the extraneous details of the fantasy world. This is more or less the exact opposite of the Tolkien method of storytelling.
So if your autogenerated API specs are The Silmarillion, or perhaps a large, dense forest of information, how do you create the best possible golden paths through the API woods? How do you reduce the need for users to stray from the path into the wilds?
To answer this question, I advocate using a variety of tools: usage data for your docs, direct customer feedback, frequent topics of support calls, and information from sales about customer requests. With some combination of these sources of information, you can figure out where to place your paths, and what form they should take, such as tutorials, charts, or procedures.
