RE: Out of Work Tech Writers - Unite!

["Ed Manley" <edmanley -at- bellsouth -dot- net>]

This thread seems to have hit a nerve; lots of good and a few not-so-good
suggestions.

I want to add another: you be the judge as to its quality!

All technical writers who work in the software development arena likely are
aware of certain failings and difficulties of software lifecycle
documentation.

Most software project documentation is developed in a waterfall progression,
where initial thought becomes a "vision", research and requirements
elicitation begin to detail functionality, analysis further identifies
requirements... and this progresses throughout development, with each
iteration of documentation essentially building on that which came before.

What we soon see is that information is visited and revisited as drill-down
and elaboration adds knowledge, resulting in information that is repeated,
often verbatim, in many documents. A sentence in a Vision Statement may
become several requirements in a Software Requirements Spec, which may
become more detailed restatements in a Detailed Design Doc, and may well
appear again in Test Cases, may become several paragraphs of text in on-line
help, yada yada yada...if you do software documentation you know the drill.

One problem is that this same information now appears in multiple forms in
multiple documents; for every change every reference to the changed info in
every doc has to be found and edited consistently. I believe that by the
mid-point in any development effort every document is inaccurate in some
way.

Version control is a huge issue - a diagram may stand alone as well as
appear in numerous documents. Make a change to that diagram and it's a sure
bet that some doc won't get changed, again, building error into the
documentation library.

Modular documentation and single-sourcing appear to be at least partial
answers to this dilemma - an item is created once, stored only once and
called by linking into any document where it is needed. This way everyone
knows where to find the current version (one source) and a change to that
item is immediately distributed into all documentation that contains it.

The item thus appears quickly and accurately in the technical
specifications, test cases and user manual and on-line help
(single-sourcing).

What if we out-of-work tech writers were to unite to collaborate on a
solution to these problems?

We could use otherwise less-productive time to investigate modular
documentation (XML?), single-sourcing, knowledge management (portals?), etc.

Among us we have the expertise, the experience, know where the problems are,
have a pretty good idea how we might improve the state of software
documentation and, most importantly, have the time and opportunity to work
on these issues that we cannot work on when employed. In my experience very
few employers have enough faith that we can solve these issues to fund the
research and development of such improved documentation practices, yet
almost all of them would pay to have us come in and implement such a
solution!

Numerous benefits come to mind - it would keep those of us who are between
contracts on a learning path, it would give us all a project to use as
"selling points" on our resume, it would help the industry as a whole, and,
perhaps most importantly, if we figure out a way to eliminate these issues
from the development process we would become the sought-after, rather than
the seekers.

In fact, I can see great possibilities for a group of us out-of-work
analysts and writers who collaborate to find a solution to then band
together into a distributed company to market this solution.

Anyone interested in spending some unemployed hours productively are
encouraged to contact me.

Have fun,
Ed



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
---
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.