[Author Prev][Author Next][Thread Prev][Thread Next]
[Author Index (this month)][Thread Index (this month)][Top of Archive]

Re: API - Suggestions on Document

Subject: Re: API - Suggestions on Document
From: "Peter Neilson" <neilson -at- windstream -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Thu, 19 Apr 2012 15:47:03 -0400

Seems to me you are writing two entirely separate documents, and should not squish them together. There is clearly no need to put an explanation of the idea of an API into the technical document. Indeed, the presence of that material will suggest that the technical part is likely to be incomplete.

Two audiences, two documents.


On Thu, 19 Apr 2012 14:47:29 -0400, Roberta Hennessey <rahennessey -at- gmail -dot- com> wrote:

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

--

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 neilson -at- windstream -dot- net -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

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

References:
API - Suggestions on Document: From: Roberta Hennessey

Previous by Author: Re: Clashing Initialisms
Next by Author: Re: What's in a name?
Previous by Thread: API - Suggestions on Document
Next by Thread: Re: API - Suggestions on Document

[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]

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

Sponsored Ads