Re: API - Suggestions on Document

Subject: Re: API - Suggestions on Document
From: Lauren <lauren -at- writeco -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Thu, 19 Apr 2012 13:30:52 -0700

On 4/19/2012 11:47 AM, Roberta Hennessey wrote:

The audience for this new document is both technical and very
non-technical. The API is a .NET web services (asmx files).

I agree with Robert, you are describing two different documents. Are you certain that you are drafting the document for a technical audience? Sometimes, non-technical documentation is used for reference by technical people, but this does not mean that the document needs to be written for the technical audience.

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.

You seem to be describing a Use Case diagram, but use cases involve how people will use a system.

http://www.gatherspace.com/static/use_case_example.html

http://www.uml-diagrams.org/use-case-diagrams-examples.html

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.

Basic flowcharts work well for business and system processes.

http://www.bestflowchart.com/screenshots.htm




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


Follow-Ups:

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

Previous by Author: Re: Tricky capitalization
Next by Author: Re: The Whatchamacallit
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