Miguel Afonso CaetanoI just recently noticed that there are not many in-depth resources about SDK documentation for technical writers. I think this presentation provides a good "no frills" overview of the topic:
"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."
#TechnicalWriting #SoftwareDocumentation #SDKs #SDKDocumentation
