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