Re: FWD: Help! New Job, No Docs, Big Company

Subject: Re: FWD: Help! New Job, No Docs, Big Company
From: "Eric J. Ray" <ejray -at- RAYCOMM -dot- COM>
Date: Fri, 2 Oct 1998 11:57:42 -0600

At 09:28 AM 10/2/98 -0600, you wrote:
>Name withheld upon request. Please reply on list.
>I just got a position as a senior tech writer for a new company
>experiencing tremendous growth. Much of their growth was the result of
>developers building some great software. You guessed it; there is no
>documentation. If all of our developers were on a plane and it crashed,
>so would the business. It looks like the developers would have to spend
>a lot of valuable time with me so I could write the technical
>documentation. I don't understand code, so they can't let me figure it
>out for myself.
>
>There is also no documentation on the business level. The accounting
>process grew around these software applications. And the accountants
>
>I could drown in thinking about all the documentation needed here. But
>what I need is an approach to tackle this: a business analyst approach?

Yes, that's a start. In addition to the good points from Stephen
(start small and don't overpromise), Richard (get buy-in, then
be slow and systematic), Beth (Use Cases), and Michael
(business analysis and get more help), I have a few thoughts.

First, starting very high-up, it sounds like you (or your company)
have at least three genres of documentation to worry about.
1) User documentation--you didn't mention it, but I'm assuming that
either there is none and should be some, or there's some
and it needs help. Given the other points in your post,
I can't imagine that this is a done deal.
2) Technical documentation--until this is done, you probably shouldn't
let your developers travel together. This is the what-does-it-do
and-how documentation that would give a new engineer a
fighting chance at revising and upgrading the existing program,
rather than taking lots on faith, reading a lot of code, and
essentially starting mostly from scratch.
3) Business documentation--these are the business processes that keep
the company functioning from day to day and fiscal quarter
to fiscal quarter.

And, you (along with your boss) have some serious prioritizing
to do. Some thoughts...

* Depending on the industry and product, you might need to focus
on getting user documentation out, both to keep users happy
and keep tech support costs under control. As soon as tech
support costs start skyrocketing, you'll be in a vicious cycle that
will be hard to stop--support dollars will go to keep the phone
queues short, so documentation will get stiffed, so more support
is needed, etc. It doesn't have to be so, but often is.

* In a startup software company, particularly if it's a consumer
product or one developed and upgraded in Internet time, getting
developer time to backfill current technical documentation
voids might not be the best use of anyone's time. Figure out
if the time to do the technical documentation is close to the
rev cycle of the software, and consider focusing on getting the
tech docs right on the next revision. It isn't ideal, but might
be more feasible.

* From a business perspective, getting solid business practice
documentation in place is invaluable, but getting the time and
resources to do so is iffy at best--it's often hard to justify because the
ROI isn't apparent or terribly quantifiable. However, better to
do it now than to try to do it later. Particularly because of the
new personnel in the accounting group, tagging along and scamming
off of the training notes etc. that the new people accumulate
would be a good start--turning the accounting groups monitor-based
-postit-note-documentation into real docs would be the best
way.

* In the great unknown that is your accounting etc. software,
find out first if you're Y2K compliant. If not, then you'll have
a whole new mess of problems that you (and your company) will
likely need some help with, but if you're currently using a
non-Y2K compliant system, your documentation efforts will
need to focus more on systems and processes for effective
remediation and upgrade than on what people actually do.
If you focus on user-level business documentation and you're
not Y2K compliant, you'll reinvent this same wheel next
year.

* Depending on the level of commitment to technical
documentation and trust among you, your boss, your
internal customers, and everyone on the outside looking
in, you'll probably need to prioritize sequence of what
gets done when as well as quality of what gets done.
While you're undoubtedly feeling a strong push to get
GREAT docs out, your time might well be better spent
heeding the 80/20 rule and covering the big bases
as quickly as possible, then worrying about great docs
on the next go around. This requires a lot of trust and
a solid commitment to tech pubs, but would likely
be the best approach. After you've done the quick and
dirty 80% across the board, fleshing out the details
and hammering it all into good docs will be much easier
because you'll be more intimately familiar with the whole
company and the interrelations.

Eric

BTW, we're looking for contract gigs, so please feed
any leads you have in this direction. Thanks!




*********************************************************************
Eric J. Ray TECHWR-L Listowner
ejray -at- raycomm -dot- com http://www.raycomm.com/

Syndicated columnist: Rays on Computing
Technology Department Editor, _Technical Communication_
Co-author of _Unix Visual Quickstart Guide_, _Mastering HTML 4_,
_Dummies 101: HTML 4_, _HTML 4 for Dummies Quick Reference_, others.


From ??? -at- ??? Sun Jan 00 00:00:00 0000=



Previous by Author: FWD: Help! New Job, No Docs, Big Company
Next by Author: Re: single source print+html
Previous by Thread: Re: Help! New Job, No Docs, Big Company
Next by Thread: JOB: Tech Writer, Reading, MA, USA


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


Sponsored Ads