Re: anyone else in the same boat?

[Sandy Harris <sandy -at- storm -dot- ca>]

Sella Rush wrote:

I agree with almost everything Stella wrote. Overall, I'd say that was the most
sensible post I've seen in either this thread or the never-ending process/product
debate currently going on in a couple of other threads.

That said, I'd like to add a suggestion or two. I'll mercilessly snip her text
to the bits I need for context...

> Suggestions:
> 
> 1.  You need to keep thinking both short and long range.  This can get
> complicated, but it's important.
> 
> Initially, the short range are those concrete projects the manager
> identified.  These are your absolute, number one first priority and should
> *not* be bogged down while you set up templates and processes.  If the
> manager doesn't have a project, pick one for yourself.  As Andrew
> said--start small.  And he doesn't mean an organizational project--he means
> a project that has tangible value to your employer--a white paper, some web
> content, a useful graphic or diagram.  You want your manager to feel they
> were right to hire you.

Another way to prioritise is to put the reference material first. You need
both the rather dry basic reference stuff -- e.g. for an API, the names,
arguments and return values of all the functions -- and the more narrative
text that covers the conecpts and how to use the thing.

Doing the reference stuff first has a few advantages. It may be partly done
already, in the spec or the comments or internal docs the team have to have
to use each other's stuff. It may be easier because it is in small chunks,
one per function or whatever. It produces an immediate payoff; it may be all
some readers need. Finally, doing it first means you have it to refer to
when you tackle the other stuff and you get to ask many of your questions
before you have to tackle a concepts doc.

> 3.  Be sensitive to the need for internal documentation.  This is where I
> fell down on the job because it simply didn't occur to me.  We all know
> about documentation that needs to accompany a product; we know about
> marketing material and communicating with our clients and potential
> customers or investors.  But there is a very definite need for communication
> within your own team. One team member solves a problem or develops a neat
> little utility that's useful to everyone.  You can help by helping the team
> member document it or disseminate the info.

All too often, such documentation does not exist or (worse) is outdated.
There may be a spec that does not describe the product, marketing material
that doesn't do so either, ...

It may or may not be part of your job to fix such problems, but in my view
it is definitely part of the job to raise the questions if such things
become apparent to you.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Take XML and Tech Writing courses online!  Our instructor-led courses
(4-6 hrs/wk) give you "hands on" experience at your convenience. STC members
get 20% off!  http://www.online-learning.com/index.html.
---
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.