RE: what would you say?

[Paul Hanson <PHanson -at- Quintrex -dot- com>]

Hi Geetha,

It depends. Beena V Katekar's list is a good start. I would add that, for
documenting software, two additional factors to consider are:
I. How familiar you are with the technical side of the program?
II.What is the availability of specs?

I. How familiar you are with the technical side of the program?
It takes *me* less time to document a new program if I know the underlying
purpose of the program, beyond the marketing and hype. How is the user going
to use this? What are the real-life situations they are going to be in with
this software and how do you do them? That's what I need in my
documentation. If I am unfamiliar with the program and what it's supposed to
do, it takes me longer because I research, ask questions, and "play" with
the program longer. 

I draw on two recent projects to explain II. I've recently seen that with
detailed specs, if I am unfamiliar with the technical side of the program,
it may still take more time than I anticipated to write the doc. So
"detailed specs" is not equal to "reduced writing time." Conversely, "no
specs" is not equal to "increased writing time." My two examples from within
the last two weeks:

A.
My current project has a 68 page *detailed* spec <as in field-by-field,
button-by-button>. Additionally, there is a 36 page Word doc of all the
screens, as they were initially designed. Between the two, a lot of my
content is there and a majority of my questions are answered. The specs say
"Click the Add button. The <new window> screen displays. The information on
this second window reflects the record the user added on the previous
window." This simplistic example is easy to prove/disprove by doing it in
the .exe file installed on my PC. And actually, for this specific project, I
am doing more *editing* of the specs, based on how the .exe file on my PC
behaves, simply because the specs go field-by-field, in the same order that
I would document them. Even with that information to start out with, I am
finding this project taking longer because I am having to ramp up on the
technical ramifications of doing what this program allows you to do. I
started diving into it on Monday and hope to be done today.

B.
For the project I worked on last week, there are no specs. The program is
currently installed on a programmer's laptop. He is installing it at a
client site on Monday and for the install, I needed a PDF of the section of
the program the client will be working with. For 1.5 days, I sat at his
laptop at a table in his office and played with the program. For a couple of
hours, on the first day, the programmer sat next to me and we went through
the program, screen-by-screen. I took 10 pages of notes. For the remaining
time, I sat at his table in his office writing the document. I asked him a
couple of questions, made a couple of suggestions for the user interface,
but for the most part, I based my document on my note-taking.

So, in conclusion, this question has to be answered on a project-by-project
basis. The two items I would add to Beena V Katekar's list is 1) the
availability of specs (or lack of specs) and 2) how familiar you are with
the technical side of the software <if documenting software> or hardware <if
documenting hardware>. 

That is how I would answer the question: it depends.

Paul Hanson
Technical Writer
RoboHelp MVP
Quintrex Documentation Team
Quintrex Data Systems
http://www.quintrex.com
Comments re: Quintrex Documentation? Use documentation -at- quintrex -dot- com to
provide feedback!

> Subject: What would you say?
> From: Geethashree H <Geetha -dot- S -at- kshema -dot- com>
	<snip>
> What would be your answer when you are asked,"How do you go about writing
> documents and planning time frames?"
	|
	From: Beena V Katekar <Beena -dot- Katekar -at- kshema -dot- com>
	<snip>
	The factors which determine your time frame are
> 1. the kind of work 
> 2.how many people are working on a particular  project
> 3. how is ur work situated in the project as a  whole.
> 4.if, your planning to your time frame , it is always better to keep the
> buffer time to keep urself in the safer side. 
	<snip>


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

Order RoboHelp X3 in November and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/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.