RE: TECHWR-L Digest, Vol 80, Issue 10

["McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>]

Good point. On the origin side, we use <an industry standard> as a base, and that standard already does a good job of explaining itself.
Integration with major third party apps and systems comes in two flavors:

 - install our stuff and configure the third-party app to recognize us, which is just some settings and options in the app, so no programming (this has become the most common case)

 - create a bridge (which does need some coding, but which then mostly relies on the SDK of the unknown app to specify the where-and-how)

For customers who are coding their own apps (not relying on 3rd-party)... well, somewhere between <an industry standard> and our own "secret sauce" is the scope of the 'Best Practices' that somebody has decided they want.

For established third-party apps, our product presents as a standardized item (our name is picked up from a standard interface, so nothing to say there - the coder can pass it through to his/her user-visible interface or can translate it as s/he sees fit). For yet-to-be-written apps, the presentation is entirely at the whim of the application coder. We are a resource that they can present in any way they please... or that they can hide entirely from their users and run entirely under-the-hood.

> -----Original Message-----
> From: techwr-l-bounces+kevin -dot- mclauchlan=safenet-inc -dot- com -at- lists -dot- techwr-
> l.com [mailto:techwr-l-bounces+kevin.mclauchlan=safenet-
> inc -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Bowes, Rebecca
> Sent: June-11-12 8:37 AM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: RE: TECHWR-L Digest, Vol 80, Issue 10
>
> A Best Practices section doesn't necessarily need to cover best coding
> practices. It could include recommendations for how best to present
> your product within that third party app -- guidelines for the
> interaction, the display, whatever, based on your experience working
> with other customers. It helps new customers benefit from the
> experiences of others.
>
> Rb
>
> -----Original Message-----
> From: techwr-l-bounces+rebecca-bowes=idexx -dot- com -at- lists -dot- techwr-l -dot- com
> [mailto:techwr-l-bounces+rebecca-bowes=idexx -dot- com -at- lists -dot- techwr-l -dot- com] On
> Behalf Of techwr-l-request -at- lists -dot- techwr-l -dot- com
> Sent: Monday, June 11, 2012 1:55 AM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: TECHWR-L Digest, Vol 80, Issue 10
>
> Send TECHWR-L mailing list submissions to
>       techwr-l -at- lists -dot- techwr-l -dot- com
>
> To subscribe or unsubscribe via the World Wide Web, visit
>       http://lists.techwr-l.com/mailman/listinfo/techwr-l
> or, via email, send a message with subject or body 'help' to
>       techwr-l-request -at- lists -dot- techwr-l -dot- com
>
> You can reach the person managing the list at
>       techwr-l-owner -at- lists -dot- techwr-l -dot- com
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of TECHWR-L digest..."
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> TechWhirl's Email Discussion List is Sponsored by:
>
> 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
>
> Today's Topics:
>
>    1. TECHWR-L Premium Jobs, Events, and Announcements (TechWhirl
> Admin)
>    2. Developer "Best Practices" content (McLauchlan, Kevin)
>    3. Re: Developer "Best Practices" content (yehoshua paul)
>    4. RE: Developer "Best Practices" content (Erika Yanovich)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Sun, 10 Jun 2012 13:40:40 -0500
> From: TechWhirl Admin <admin -at- techwhirl -dot- com>
> To: Techwr-l <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: TECHWR-L Premium Jobs, Events, and Announcements
> Message-ID:
>       <CAC8ceKkeyBiw=jxt-
> OkSBndvaNXohNKw6LUY__jWbxM2dJAB=Q -at- mail -dot- gmail -dot- com>
> Content-Type: text/plain; charset=windows-1252
>
> *TECHWR-L Premium Jobs, Events, and Announcements***
>
>
>
> Posted on Sunday, June 10, 2012
>
> ________________________________________________________
>
> TECHWR-L Premium Ads
>
> You received this message because you're a subscriber to TECHWR-L.
> This ad
> posting is sent daily directly to all list members to help
> underwrite the costs of the list (just as ads in a newspaper, magazine,
> or
> journal underwrite the costs of those publications).
>
> In this posting, look for the following:
>
> ** Learn How Doc-To-Help Works in Five Lunch Breaks*
>
> ** Try MadCap Flare 8 Today, Free 30 Day Trial*
>
> ** Latest Tech Comm Jobs*
>
> ** Latest articles, news and events from Tech Writer Today Magazine*
>
> *################################################################*
>
> *Learn How Doc-To-Help Works in Five Lunch Breaks*
>
>  Learning how new tools work can be an intimidating task. We all are
> busy.
> We all have deadlines. There never seems to be time to look at new
> things.
> With that in mind, Doc-To-Help is rolling out a new tutorial series
> that is
> designed to give you a fundamental understanding of how Doc-To-Help
> works
> in five short, self-paced lessons. The first release includes two
> versions:
> one for those who want to use Microsoft Word as a source and another
> for
> those who want to use Doc-To-Help?s built-in editor.
>
> Learn More About Doc-To-Help?s Lunch Breaks: http://bit.ly/Kbt0Og
>
> *################################################################*
> Latest from Tech Comm Jobs
>
> ?       Technical Writer, Montreal, Quebec, Canada -
> http://bit.ly/IMDleU
>
>
>
> Got a role you want promoted on TechWhirl.Com and to our Email
> Discussion
> Group? Learn more about our Jobs Site TechCommJobs |
> http://bit.ly/AboutTechCommJobs
>
> *################################################################*
> TechWhirl?s Tech Writer Today Magazine:
>
> Every week TechWhirl publishes articles, news, and events focusing on
> technical communications and technical writing.
>
> Latest Articles (http://techwhirl.com):
>
>
>
> ?       TechWhirl: Technical Communication Recap for June 8, 2012
>
> | http://bit.ly/L3GQmm
>
> ?       Enjoy Tech Writer <http://twitter.com/search?q=%23TechWriter>
> This
> Week, with curated posts in tech
> comm<http://twitter.com/search?q=%23techcomm>
> , #UX <http://twitter.com/search?q=%23UX> and more |
> http://bit.ly/Lv0KGn<http://t.co/UA68nhZP>
>
> ?       Take the weekly tech comm poll: skills needed to survive and
> thrive
> | http://bit.ly/JWL9Ax
>
>
>
> Latest Tech Comm News (http://news.techwhirl.com):
>
> ?       IBM Enhances CLM (Collaborative Lifecycle Management) Solutions
> http://bit.ly/MVC2lJ  (June 9 2012)
>
> ?       Data Conversion Laboratory?s ?Convert On Demand? Fuels New
> Revenue
> with Dormant Content http://bit.ly/LzG8ZA (June 8 2012)
>
> ?       Usability Professionals Association (UPA) Rebrands as UXPA
> http://
> bit.ly/LEwK9j <http://t.co/0vJAjgk5> (June 7 2012)
>
>
>
> Interested in getting the news first or sharing a little?  Join our new
> LinkedIn Group?Technical Communication News:
> http://linkd.in/TechCommNews
>
>
>
> *################################################################*
>
> *Follow TechWhirl?s Tech Writer Today Magazine*
>
> Google + Page, Behind the scenes @ TechWhirl: http://goo.gl/XwPt3
>
> Follow us on Facebook | http://goo.gl/tDrW7* (Posts and discussions)*
>
> TechWhirl on Twitter | http://goo.gl/itjDg  (posts and technical
> communication news)
>
> Follow on RSS | http://goo.gl/msLzu (the site via RSS feed)
>
> Technical Communication News on LinkedIn: http://linkd.in/TechCommNews
>
> Updates from TechWhirl delivered to your email in box |
> http://bit.ly/tjshxU
>
> *Reaching our Readers*
> Email Ads
>
> Advertisements on the TECHWR-L Premium Announcement posting
> cost $50 to contact over 3000 TECHWR-L subscribers
> directly each day for a week.
>
> More Advertising Opportunities: http://bit.ly/sponsorTechWhirl
> Announcements and Events
>
> For announcements (a call for presenters) and events (conference on ?)
> that
> you specifically want to be mailed directly to all 3000+ TECHWR-L
> subscribers
> in the TECHWR-L Premium Daily Announcement, please contact us at
> (admin -at- techwr-l -dot- com).
>
> Also, please be certain to add your events to our TechWhirl Calendar,
> which
> is a free resource on our magazine for announcements, activities, and
> events: http://www.techwhirl.com/events
>
>  Job Postings
>
> Please do not directly post jobs to TECHWR-L.  Instead, add it our new
> website http://jobs.techwhirl.com
>
> For a limited time all postings will be promoted on our magazine
> TechWriterToday.Com
> and be featured in our TECHWR-L Premium Daily Announcement.
>
>  Learn more about TechCommJobs | http://bit.ly/AboutTechCommJobs
>
>
> ------------------------------
>
> Message: 2
> Date: Sun, 10 Jun 2012 19:24:16 -0400
> From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
> To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Developer "Best Practices" content
> Message-ID:
>       <D1E2C829C5011E4A84DAF8A184DD7CDA020D1681B3 -at- BEL1EXCH02 -dot- amer -dot- sfnt -dot- 
> local>
>
> Content-Type: text/plain; charset="us-ascii"
>
> This is for list members who document software/hardware/firmware
> products where a customer might be expected to program an app that uses
> your product, or to integrate your product into a third-party
> application.
> In other words, with your product you supply a developer's toolkit.
>
> An inhabitant of a corner office has decided that our documentation
> lacks a page or section that would be Best Practices for programmers
> using our SDK.
>
> >From my point of view, the entire SDK docs are what a
> customer/developer might want to know.
>
> Some years ago, that portion of the docs included a Tips and Tricks
> page until I was asked to remove portions that had become outdated. The
> whole thing went away.
>
> I see no need - and I think even corner-office would agree - for
> material that any programmer should already know or can find in an
> O'Reilly book (do they still publish those?), in a C# for Dummies or a
> Java for Dummies book or similar.
>
> Our headers and sample code are as standardized as we can make them,
> and include comments relevant to each major language that we support,
> so there's nothing additional to say about compile options, etc.
>
> What do y'all do on this topic?
>
>
> -          k
>
>
> The information contained in this electronic mail transmission
> may be privileged and confidential, and therefore, protected
> from disclosure. If you have received this communication in
> error, please notify us immediately by replying to this
> message and deleting it from your computer without copying
> or disclosing it.
>
>
>
> ------------------------------
>
> Message: 3
> Date: Mon, 11 Jun 2012 07:20:48 +0300
> From: yehoshua paul <yehoshua -dot- p -at- technicalwriting -dot- com>
> To: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
> Cc: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Re: Developer "Best Practices" content
> Message-ID:
>       <CABz1xA1S7+2M77ygmVu8D8s8qC8ZtAmMrsVSFTYEMUO84sAqeg -at- mail -dot- gmail -dot- c
> om>
> Content-Type: text/plain; charset=ISO-8859-1
>
> To me the answer is obvious: what do your customers say?
> Have you ever gotten any feedback from your customers saying that they
> need
> such a section, or that a Tips and Tricks page would help? Or do they
> agree
> with you and think that such information is redundant for expert users
> like
> them.
> If you can find out what your readers want than that is the answer to
> your
> question.
>
> Disclaimer: This is my generic answer for these types of questions. I
> personally do not document products where you supply SDK toolkits.
>
> Have a great day,
> Yehoshua Paul,
> Community contributor and documentation expert
> http://technicalwriting.com/
>
>
>
> On Mon, Jun 11, 2012 at 2:24 AM, McLauchlan, Kevin <
> Kevin -dot- McLauchlan -at- safenet-inc -dot- com> wrote:
>
> > This is for list members who document software/hardware/firmware
> products
> > where a customer might be expected to program an app that uses your
> > product, or to integrate your product into a third-party application.
> > In other words, with your product you supply a developer's toolkit.
> >
> > An inhabitant of a corner office has decided that our documentation
> lacks
> > a page or section that would be Best Practices for programmers using
> our
> > SDK.
> >
> > From my point of view, the entire SDK docs are what a
> customer/developer
> > might want to know.
> >
> > Some years ago, that portion of the docs included a Tips and Tricks
> page
> > until I was asked to remove portions that had become outdated. The
> whole
> > thing went away.
> >
> > I see no need - and I think even corner-office would agree - for
> material
> > that any programmer should already know or can find in an O'Reilly
> book (do
> > they still publish those?), in a C# for Dummies or a Java for Dummies
> book
> > or similar.
> >
> > Our headers and sample code are as standardized as we can make them,
> and
> > include comments relevant to each major language that we support, so
> > there's nothing additional to say about compile options, etc.
> >
> > What do y'all do on this topic?
> >
> >
> > -          k
> >
> >
> > The information contained in this electronic mail transmission
> > may be privileged and confidential, and therefore, protected
> > from disclosure. If you have received this communication in
> > error, please notify us immediately by replying to this
> > message and deleting it from your computer without copying
> > or disclosing it.
> >
> >
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > 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
> > yehoshua -dot- p -at- technicalwriting -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
> >
>
>
> ------------------------------
>
> Message: 4
> Date: Mon, 11 Jun 2012 05:13:51 +0000
> From: Erika Yanovich <ERIKA_y -at- rad -dot- com>
> To: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>,
>       "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: RE: Developer "Best Practices" content
> Message-ID:
>       <B2076404CA044A4EAE79FFD4E4D136DC043271BB -at- EXRAD5 -dot- ad -dot- rad -dot- co -dot- il>
> Content-Type: text/plain; charset="us-ascii"
>
> 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
>
>
> ------------------------------
>
> _______________________________________________
> You are currently subscribed to
> TECHWR-L.
> To unsubscribe send a blank email to
> http://lists.techwr-l.com/mailman/listinfo/techwr-l
> Send administrative questions to admin -at- techwr-l -dot- com -dot- 
>
> Visit
> http://www.techwhirl.com/ for more resources and info.
>
> Looking for the archived Techwr-l email discussions?  Search our public
> email archives @ http://techwr-l.com/archives
>
> End of TECHWR-L Digest, Vol 80, Issue 10
> ****************************************
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 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 kevin -dot- mclauchlan -at- safenet-
> inc.com.
>
> 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
The information contained in this electronic mail transmission 
may be privileged and confidential, and therefore, protected 
from disclosure. If you have received this communication in 
error, please notify us immediately by replying to this 
message and deleting it from your computer without copying 
or disclosing it.



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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