RE: Developer "Best Practices" content

Subject: RE: Developer "Best Practices" content
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 11 Jun 2012 00:29:06 -0700 (PDT)

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.

http://bit.ly/doc-to-help

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Previous by Author: Re: Is localisation obligatory?
Next by Author: Re: Bullet Styles
Previous by Thread: RE: Developer "Best Practices" content
Next by Thread: RE: TECHWR-L Digest, Vol 80, Issue 10


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads