Who Writes the Examples of The SDK?

By | November 2, 2017

There is broad agreement that in an API (SDK), perhaps the most essential element (and the one for which the non-dedicated programmer is searching) are the samples. So what’s the writer’s role in all this? A technical writer must always be in front of the problem and the proposed solution, from the customer’s point of view.

 

The technical writers who represent the users should therefore be closely involved with each word in the documentation set. And if the documentation set contains examples, the technical writer must make them too.

 

This is the patristic theory. Practically speaking, this is not a requirement.
In my entire time as an API writer, I never once asked to write an example. I would not trust myself to do it either. I learned several programming languages, I worked more than 15 years in software engineering environments, but I still did not say “I can program in Java!”

 

My SDK Documentation Approach is to represent the user, to guide the engineers through the topics that a user would seek and to provide the engineer with the material of the estimated origin. This applies to the overview, the reference material and the examples.

 

By encouraging engineers to give examples, I point out the same tests they have developed for QA, their own units, or for code developed by Field Integration teams (usually developed SDKs from custom APIs developed for users). The result of this approach is the real examples that demonstrate broad applicability and which are re-accessible to users.

 

Therefore, for the purposes of API documentation, I would rather be a programmer-technician writer to be a writer of technology. But even if you’re a programmer, you can refer me to the outside service or technical support engineer to get accurate, practical and applicable examples.

 

Related posts: