RE: API - Suggestions on Document

Subject: RE: API - Suggestions on Document
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: Roberta Hennessey <rahennessey -at- gmail -dot- com>, tech writer tech writer <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 20 Apr 2012 15:36:43 -0400

I'm about to need something very similar, for similar reasons.

I just spent a few days hurting my head rather badly, explaining
some of our product concepts in a mostly pictorial way, since
the many words I'd generated over the years have become... too many. :-)

Each time a customer (or pre-Sales Engineer) would come up with
an awkward question or - worse - would predicate a big purchase
on the ability to use a product in a specific and obscure way,
I would write a new page or add a section to an existing one
(either explaining how they could do it, or explaining why it
was not possible).

My resulting drawings from the re-work over the past several
days still have (perhaps too many) words in them - the IKEA
model of product instruction has proven elusive in my case - but
they're still a lot more organized and comprehensible than the
previous accretions. But that's for product configuration and
operational use, not so much for API-ish tasks of developing
customer apps against our framework or integrating with
third-party systems.

We've always had C, Java, etc. APIs, but now we're coming up
with a product and an associated API that could be usable by
less techie customers, so I have almost the same need that
Bobbi just outlined. I'd love to see a friendly, informative
flow of work or development that I could /s/t/e/a/l/ adapt
for my situation. Inspiration and approach. Yeah.

> -----Original Message-----
> From: Roberta Hennessey
> Sent: April-19-12 2:47 PM
> To: tech writer tech writer
> Subject: API - Suggestions on Document
> I have been tasked to write a new version of existing API docs.
> The audience for this new document is both technical and very
> non-technical. The API is a .NET web services (asmx files). My idea is
> to
> create a very basic, simple, introductory concept chapter and include
> simple graphics (and maybe a work flow doc) to explain what an API does
> and
> how the two parts of this one work.
> I am writing in Word, converted to pdf and the document is used both
> online
> and hard copy. I can think of some innovative ways to use bookmarks
> and
> links in Word for the online users but what I'm really after is using
> the
> graphics to convey how the API works.
> I wonder if anyone on the list has used graphics or seen really good
> example of using graphics to explain a work flow. Work flow diagrams
> are
> fine, but really non-technical users need simple line art (IMHO). I'm
> asking if anyone can point me to some of their favorite "graphics
> explaining how something works" so I could learn by example and/or get
> my
> creative juices flowing.
> Any suggestions appreciated. No time to plan to use other types of
> docs,
> etc.
> Thank you.
> Bobbi

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.


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 for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @


API - Suggestions on Document: From: Roberta Hennessey

Previous by Author: RE: Interviewing technical writers
Next by Author: RE: Monospace fonts
Previous by Thread: RE: API - Suggestions on Document
Next by Thread: Re: API - Suggestions on Document

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

Sponsored Ads