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.
I had an interesting experience last week. First, some background.
I'm documenting an HR web portal. This portal is used by clients that
have outsourced their human resource management to my company and the
portal is for the client HR administrators, Benefits Analysts, and
Employees to configure their benefits, contact information, and
financial/professional growth.
To do this, you go through a series of steps, from creating clients,
configuring the clients, adding employees, configuring employees,
creating custom web pages, etc.
Anyway...for the last 6 months, I've been creating these
configurations and web pages. I'd created quite a collection of pages
and configurations.
Last week, application management did a server refresh. This entailed
deleting the dev environment and bringing everything from the
production environment down to the dev environment. The good news is
that the dev and prod environment are back in sync. The bad news is
that since I was in my own personal sandbox, so to speak, all of my
files went pfffttt. Gone. No more. Poof. and since it was a
development environment, it wasn't backed up besides the codes being
on VSS.
At first, I was really pissed, and that lasted a few hours. Then I
started to recreate what I had, and here's the important part, USING
MY OWN DOCUMENTATION TO DO THIS.
Well...let me tell you...I thought my documentation was pretty much
spot-on accurate...until now. It is amazing what I learned through
doing this. Things like poor organizational issues, missing
procedures, erroneous processes, all kinds of things.
I don't think my stuff before was poorly written. I think what
happens is that as you learn about the product you are writing about
and as you learn the technology, you learn stuff that affects
everything you've written prior to that point.
Now...I'm not suggesting that you delete your system and start from
scratch. I do, however, now believe that everything you've ever
written needs to be reviewed periodically, and not just immediately
after it's been written. Give it a few months and then approach it
with a fresh mind.
John Posada
Senior Technical Writer
"So long and thanks for all the fish."
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l
