Re: A documentation suite for dot-nets?

Subject: Re: A documentation suite for dot-nets?
From: Tom Murrell <trmurrell -at- yahoo -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 16 Oct 2000 06:30:50 -0700 (PDT)

There are lots of interesting technical communications points in this
email. I'll try to make my comments as interesting. Tom Murrell

--- stephanie -at- storerunner -dot- com wrote:
> Are there other techwhirlers who are part of a dot-net company? I
> need some ammunition (if I turn out to be right, that is) <g>
>
> My company started off as a dot-com. That is to say, our sole
> purpose was to have a really awesome destination site on the web.
>
> Now we are sinking into the B2B pool, and our company heads have
> officially touted (over and over again) that we are now a
> network...hence the dot-net alias. This means that our own website
> becomes merely a display of our capabilities, and our revenue is now
> generated via partnerships with other sites. We become the invisible
> techonology that allows other sites to be cool.

For somebody who "agrees with this business strategy" (see your comment
below), you sure seem to use words that disparage it. "Sinking into the
B2B pool," "Merely a display of our capabilities," are two examples.
Are you on-board with this thing? Or are you simply saying "well, if we
have to, we have to." If this is how you communicate your support to
your managers and coworkers, they might not think you are really behind
the project. So they might not "include you in" the work of the
project.

> I agree with this business strategy. It makes sense for us. But I
> am ||this close to sending an email to the CTO saying "Hey! Wait a
> minute!" I am the ONLY tech writer here. We have 6 proprietary tools
> that need user help and training; plus requirements are withering on
> the vine -- leading to development havoc in our eng dept (I have
> offerd to help, but they just keep running around in circles,
> saying "yeah we want to bring you in but there is no time right now
> [blech])

Okay, so they don't have time to teach you what you want to know, and
you're only one person. That defines what they are doing. What are you
doing to address the situation? Look for ways you can help rather than
just bugging them because they are helping you. What DO they need help
with? Show a willingness to learn what you need to meet THEIR needs,
and they might be more open to your ideas (also below, and which aren't
half bad, IMHO).

> So, "fine!" I've thought. "At least we dont have outsiders trying to
> make sense of this stuff! At least it is only our own people who are
> neglected, ill-advised, never having complete documentation!" (Oh, I
> forgot to mention..they've only asked me to document 1 of the tools;
> other than that they have me analysing and communicating work
> processes - I have become an add-water-and-stir business analyst)

I know you think I'm being harsh, but it appears they've shunted you
aside because you aren't helping with the project. Is there any way you
can change your tactics to be more effective? Don't tell your
developers that they have to drop everything (I'm speculating here; you
didn't, exactly, say this) and help you get the documentation out. You
may be right, but they're obviously focused on getting the product out.
You will need to be the one to make the plan and do the work, probably
without much hand-holding, to get some documentation out WITH the
product. Focus on what YOU CAN DO, rather than on what they're not
doing.

> But now here we are. Standing on the mountain top and roaring:
> partners come this way; we are dot-net.
>
> I want to speak out...how on earth can we claim to be dot-net, when
> we have no API documentation? No "how to use our service"
> documentation? Nothing! Our information share stops after the sales
> pitch, and the partner is dumped into the engineering/development
> abyss, to be later 'maintained' by a single (company-wide single
> professional services manager.
>
> I am a novice, so I don't know precisely what I would document for a
> network partner; but I have learned enough that I am sure that
> *something* should be written. Are there experienced dot-netters out
> there who can vouch for this? Shouldn't I, as the tech writer, be
> preparing a "suite" of documentation for our partners? Can any of
> you list the typical documents comprising such a suite?

You may be a novice, but you do see some needs. I'll assume you've
already shared your perspective with management and developers, but you
haven't gotten any 'buy in.' So begin to develop the documentation you
see is needed. Don't wait for approval and don't insist on more
resources. What can you do to address the needs you've identified with
the resources you DO have? It sounds to me like that's what is needed
here.

>
> What I am thinking:
> 1.) API
> 2.) hyperlinking
>
> What else....?

I feel like I'm having an AP moment here. Since you're the only one,
apparently, who sees the need, address it yourself. Sounds like the API
needs some documentation. Start writing it. Do your documentation plan,
then execute it. I suspect that once they see you're actually doing
something one of two things will happen. Either they'll help you do
it--correct your mistakes and misperceptions (everybody has them),
point you to the resources you need, applaud your initiative--or
they'll slap your hand (unlikely) and tell you to stick to the work
they gave you. I think this last is unlikely because almost all good
companies and managers are dying to find people who will take
initiative and do what needs to be done.

Don't wait for permission. Get cracking. (And I'll be very interested
in how it plays out.)


=====
Tom Murrell
Lead Technical Writer
Alliance Data Systems
Columbus, Ohio
mailto:trmurrell -at- yahoo -dot- com
Personal Web Page - http://home.columbus.rr.com/murrell/

__________________________________________________
Do You Yahoo!?
Yahoo! Messenger - Talk while you surf! It's FREE.
http://im.yahoo.com/




Previous by Author: Re: Website for Formatting
Next by Author: Re: Am I experienced?
Previous by Thread: A documentation suite for dot-nets?
Next by Thread: Microsoft Reader


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


Sponsored Ads