RE: Starting over (long)

["Kevin Cole" <kccole -at- fuse -dot- net>]

Hi John,

It's long been a truism among C programmers that the code is always better
the second time you write it.  This is the one bit of reliable consolation
for having lost source files that didn't make it into the backup.  Sometimes
the improvements are so obvious that it almost makes sense to use the
initial coding effort as part of the design/discovery phase, and then build
a "re-code from scratch" phase into the project from the start.  

I've had the same experience with manuals and API documentation.

I think your advice to re-examine your work with this in mind is spot-on.

Thanks.


--KC



Kevin Cole
Cole Consulting
Cincinnati, Ohio USA

-----Original Message-----
From: John Posada [mailto:jposada01 -at- yahoo -dot- com] 
Sent: Monday, January 23, 2006 11:55 AM
To: List,Techwriter
Subject: Starting over (long)

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

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy.  Watch the demo at http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.