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.
Subject:Re: Ideas in Motion From:"Anthony Markatos" <tonymar -at- hotmail -dot- com> To:kkearns -at- cisco -dot- com, techwr-l -at- lists -dot- raycomm -dot- com Date:Mon, 13 Mar 2000 12:59:56 PST
Tony Markatos responds to Katie Kearns:
You are attending an excellent program. And while testing is very
important, poor organization cannot be corrected by testing.
Your class's experience [below] is just further prof that written text is a
very poor vehicle to use for documenting procedural information. To quote
Ed Yourdon "Procedure is like dance - it defies written description." What
Ed means is that procedure is asychronous - multiple things happening at the
same time and multi-decision branching. Text is very poor at describing
Flow-chart like graphics, supplemented as necessary with text, thats the way
to describe procedure.
(tonymar -at- hotmail -dot- com)
Katie Kearns wrote:
....Every student wrote a short manual on a subject they knew well.
Once they'd written the final draft, everyone brought in their manuals and
the materials needed to follow the manuals. They handed over the manuals and
materials to another student, and watched as that student attempted to
follow the procedure.
It was a disaster. A very, very, educational disaster, as my teacher
intended! Despite the simplicity of the tasks, and the weeks that the
writers poured into writing them -- plus edits of each draft by both a
fellow student and the teacher -- most of the manuals were not followed very
well. The most unexpected sentences and situations caused the testers to
stumble and make mistakes! I was astounded and learned at the very beginning
of my new career just how important testing is.