TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I'm with Erika on this. Your sample applications and the examples in your docs must illustrate best practices. Developers should be able to lift that code out of the book, and use it as is (or as close to that as possible) -- resulting in best-practice coding at least for certain sections of their code. There are a couple of obvious ways to present example code in the docs.
In the reference for each class/method/function (or whatever), you can wrap it all up with an example that shows the construct in action. Make it real-world if you can, but more importantly, isolate what it is you want to describe as much as possible. Best practice will require some additional code around your isolated example, so you include it, along with a description. An over-simple example... In C you allocate memory for a string. Your example in the docs to use a string would show allocation of that memory, assigning data to the string, accessing data in the string, then freeing the string. Maybe you do, maybe you don't explain what makes that best-practice. That's where the O'Reily factor comes in (couldn't help that).
Another way to support best practices is to provide a cook-book section. Developers have common use cases for your SDK, so you provide recipes of code to accomplish them. Again, these recipes MUST be best-practice, because you want developers to copy/paste as much as possible -- The more recognizable their code, the easier it is to support. If they copy/paste themselves into a support call, that's not good.
For an SDK, best practice extends beyond best practice for the given language. That's because the API extends the language. If it didn't, then nobody would bother. There are entire books, or even entire industries around best-practice coding for a given API. Look at how many Swing or MFC books have been written. Your SDK is even less known than MFC... surely your developers want to know what you consider to be best practice for that particular extension of the language, don't they? Here's to the "authority" in "author"!
cud
Erika said...
Hi Kevin,
We
provide such docs and customers are always asking for lots of examples.
Also, they need to know the right sequence of actions to accomplish a
typical task and alternative ways of accomplishing the same.
HTH,
Erika
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.
Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.
