SDK Reference Manuals: A flow-based approach¶
Description
SDK docs written by developers tend to be implementer oriented, not user oriented. That makes sense, since it's the implementers writing them. Unfortunately, this approach leads to some frustrating SDK reference manual experiences for users. The implementer-oriented doc writer tends to answer, "What is this built on?" As a user, I need docs that tell me, "What can I build with this?"
I provide examples of common SDK docs pitfalls, then present the approach that I used updating the SDK documentation that our developers had created. My goal was to give users of those docs a quick, enjoyable, user-oriented experience. To do so, I identified the likely use cases, or flows, of our product. I then grouped all entities (classes, functions, etc.) of the docs into these flows. For each flow, I arranged the entities in "flow order".
Having mapped out our codebase in this way, I was ready to begin adding content by following these principles:
1) In the leading lines, answer: what is this for? 2) Always link to the previous and next items in all flows and add "See Also" links. 3) Add a code example that demonstrates this entity's role in the flow. 4) Call out gotchas that are likely to get in the user's way when trying to use a flow.
This process involved editing the actual code comments and committing to git, which required buy-in and trust from the SDK team. I will touch on some of the interpersonal challenges that can arise when docs team members want to edit the devs' code, and how documentarians can feel empowered to get their hands dirty in the repo. I will discuss analytics and feedback data. And, of course, I'll show some docs makeover results.
- Conference: Write the Docs PORTLAND
- Year: 2019
