Documenting third-party software

Subject: Documenting third-party software
From: Tammy VanBoening <Tammy -dot- VanBoening -at- netRegulus -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 10 Mar 2003 13:58:03 -0700


One of the applications (StudyExpert) for which I develop both classic
end-user documentation and OLH uses .pdf forms developed in Adobe Acrobat.
Adobe Acrobat is not integrated in the application - our users use AA to
create .pdf forms with interactive fields and then the application has a
Wizard that allows the user to pull the .pdf form into the application and
use the form for data entry, manipulation, reporting, and so on.

I am currdently documenting this section of the application - the use of the
Wizard to pull the .pdf form into our application. However, to my SMEs, this
isn't sufficient. They want me to include in our end-user documentation
explicit instructions on how to first create the form in Adobe Acrobat.
Basically, they want me to lift (verbatim - down to the order of steps and
graphics themselves)) the instructions from Adobe's Online Help and place
them into our User Guides and OLH.

Of course, because of copyright laws and maintenance issues, (copyright laws
being the major player in this), I have steadfastly refused to do so. What I
have done instead is the following:

1.) Created a chapter in my User Guides that addresses the creation of .pdf
forms in Adobe Acrobat.
2.) This chapter is divided into sections, with each section specifically
for each step in the form creation procedure.
3.) I have very generically referenced the appropriate AA procedures in each
section and explicity stated what a user does/does not need to do if it
affects the Wizard in our application. For example, when creating date/time
fields on a form, the following concerns apply if the user intends to use
the Wizard to pull the form into our application. For example, in the form
fields section I have:

****************************************************************************
***********************************************************************
For time data, you must select the value of "Time" on the Format tab of the
Field Properties dialog box and you must not check the The Limit of
Characters option on the Options tab. If you check the Limit of Characters
option, this option overrides any other selections that you make on the
Format tab and the default data type is set to "short text" in the CRF
Wizard. You do not need to set any other properties on the Field Properties
dialog box for time data. StudyExpert supports all of the Time Options in
Adobe Acrobat. If you select a partial time format, for example, HH:mm, be
aware that:
* Adobe uses a substitution formula and stores a complete time as
HH/mm/ss.
* Any time that is not part of the selected format is stored as
zeroes. For example, if you select HH:mm, the substitution formula is
HH:mm:00.
When you enter a time in a date/time field, you must enter the time exactly
as the field format requires or the data for the field is not saved. For
example, if the time format for a field is HH:mm:ss and you enter a time as
06:42 (HH:mm), Adobe displays the time according to the format (06:42:00)
but passes exactly what you entered (06:42) to the database. Because the
data that is passed to the database does not match the required format for
the date /timefield, the data for the date/time field is not saved and you
cannot use the CRF in StudyExpert
For more information on setting field properties for a date/time form field,
see Creating form fields in Creating and Using PDF Forms in the Acrohelp.pdf
(the online User's Manual for Adobe Acrobat).
****************************************************************************
****************************
So, explicit instructions for our software, generic reference to AA on how
to create these fields in the first place and end-result, my SMEs still
wail. My best arguments/pleas/reasonings are falling on deaf ears. Has
anybody else run into this situation before and if so, what did you?
Also, our users aren't necessarily the brightest bulbs in the pack and in
some areas, AA combines several steps of instruction into a single step or
note. For me, that's fine, I can deal w/ that (it's not a slam on Adobe I
promise), but for my users, this can create havoc, so my SMEs are wailing
that I need to rewrite these as well. Again, maintenance issues and all - I
am saying that if the users can't figure out a third-party application from
the application's documentation and OLH, they need to get training on their
own. We are not a licensed third-party vendor for AA.
OK, enough rant. Any and all comments and suggestions are appreciated.





Tammy Van Boening
Senior Technical Writer
NetRegulus, Inc.
303-925-7721 (Direct)
303-925-7700 (Main)
303-662-9320 (Fax)
tammy -dot- vanboening -at- netregulus -dot- com
www.netregulus.com
**************************************************
Keep smiling - at least until you get your own way.




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Order RoboHelp Office X3 by March 14 and receive a $100 mail-in rebate,
plus FREE WebHelp Merge Module and FREE iMarkup Software, for a
total giveaway value of $439! Order today at http://www.ehelp.com/techwr-l

Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.



Previous by Author: RE: Opinions on www.techwritershome.cjb.net?
Next by Author: RE: Documenting third-party software
Previous by Thread: Re: Calling a Bug a Bug
Next by Thread: RE: Documenting third-party software


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


Sponsored Ads