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.
Subject:Re: Requirements from Development? From:"Wing, Michael J" <mjwing -at- INGR -dot- COM> Date:Fri, 26 Jun 1998 16:24:14 -0500
> Database, API, GUI, COM, inter/intranet app writers: I have a question
> for
> you...
>
> What do you "require" from your development/programming staff in order
> to really begin putting your documentation together from scratch; I mean,
> when you have NO other previous docs to begin with...and for GUI apps,
> you have no interface yet to see, because it's not yet been developed.
>
I mostly document Automation interfaces, therefore at the beginning of a
project I'll ask for the following:
* Typelibraries, OCXs, and Dlls that are visible in an object browser.
Failing that, I'll ask for the ODLs/ODIs/IDLs from which the executables are
made. I've created a VB program that makes skeletal topics from a file
saved through OLE2VW32.exe (an object browser). It also does most of the
topic linking. Once the skeletal topics are made, I troubleshoot the
linking and check the data types, arguments, input/output requirements,
required/optional requirements, and return values. This is all viewable in
the browser.
As a result, I have a help file with working topics, information extracted
from the browser, but no examples or descriptions.
* Rational ROSE or Visio automation diagrams. I can determine which
topics go into which help files from these. This allows me to design the
help and online manuals modularly.
* Any automation specifications, white papers, etc.
* VB source code used to create application commands on the automation
layer. I study the code to determine workflow, sequence, and interrelations
of the automation elements. I'll use snippets from the code to draft some
automation examples. As the functionality becomes more stable, I'll rewrite
the code to make some working examples.
I also extract information from previous projects and adapt it for the new
project. Because, I handle a lot of OLE information, some of the automation
is transferable from other projects. I use the information to fill out some
of the common topics
> How much time do you spend interviewing SMEs in the very beginning?
>
I get most of my information by writing my own sample code and running it
through VB. I then tweak the automation to determine limits, effects, and
interrelationships between the application and the automation. I then
script a list of quirks, things that I can't get working, things that I
can't determine the limits of, and so forth and either email or see the
programmer. I plan to only take 15 minutes at a time when I see them. It's
up to them whether the time is extended.
I also will use a Trojan horse approach. In this approach, I purposely
write code that does not work. I then take the code to the programmer and
explain my logic. Usually this gets their interest because I may have found
a bug in their application. As he/she troubleshoots the code, I ask them
everything from A to Z about the remaining automation for which they are
responsible.
