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.
(FYI: Documenting procedure is a the major thing
that
TWs do.)
Andrew Plato:
No, its not. Documenting procedures is ONE of the
things TWs do. A good TW is also documenting concepts,
terminology, explanations, and designs. procedures
are one part of a larger picture.
Tony Markos:
There is a typo in my above statement; the word "the"
should come out.
As I have posted several times: The major thing that a
TW is to do is come up with a detailed, comprehensive
understanding of the essential end-user tasks, and how
all those tasks interrelate - with special emphasis
placed on understanding the interrelationships.
Andrew Plato:
The MAJOR thing TWs do is understand, digest, and
explain information. Explaining task flows is ONE
subset of that.
Tony Markos:
>From the Gospel according to Ed Yourdon: "ONLY by
following the flow of data [in task analysis] can we
come up with an understanding [and therefore be able
to explain to others] the underlying logic of a
system".
Andrew Plato:
If you focus all your energy on process, you will
not produce good documents.
Tony Markos:
If we don't put enough energy on process, you will not
produce good documents. Come on Andrew, you know it:
Almost always, the main problem is that not enough
effort has been placed on process. Thats the major
reason why so much documentation is so disjointed and
disorganized.
Andrew Plato:
A procedure without context is worthless.
Tony Markos:
Exactly, thats why we create Context diagrams (a
special kind of Data Flow Diagram).
Andrew Plato:
Furthermore, one of the problems with a lot of
technical manuals is that they only document
procedures.
Tony Markos:
I never said that the other things you mention do not
need to be documented. Just that task anlaysis should
always be done first, and that the other stuff is of
secondary importance.
Andrew Plato:
Following a procedure without understanding what
you're doing it counterproductive.
Tony Markos:
Yes. And only Data Flow Diagrams give us the big
picture understanding.
Andrew Plato:
Moreover, if you understand how something works, the
procedures and tasks often become self-evident. Making
them less important.
Tony Markos:
Right, with a good higher-level Data Flow Diagram, you
often don't need written procedure.
Andrew Plato:
Furthermore, Yourdon is well-know for describing how
to design software.....
Tony Markos:
Data Flow Diagrams are not a "software thing". They
can be used on completely manual systems. They were
first used back in the early 1890's, when there were
no computers - only people doing tasks.
(Forget about the other posts talking about weaving
machines back in the 1800's. I mean real he-man
software.)
Andrew Plato:
Yourdon was not tech writer and his ideas are not
directed at tech writers (exclusively.)
Tony Markos:
Data Flow Diagrams are a techical communications tool.
Andrew Plato:
But software development and design is NOT the same
as documentation.....
Tony Markos:
There are many simularities between the design of user
friendly (i.e., minimal skips and
jump-to's)documentation and the design of lightly
coupled/highly cohesive software modules.
Andrew Plato
...Communication with people isn't like that [software
systems]. It has subjective metrics and processes. And
the rules change from reader to reader. How people
interpret the data is dynamic and volatile....
Tony Markos:
Data Flow Diagrams are just as appropriate for
documenting manual procedure as for automated
procedure. I first learned about them working as an
Industrial Engineer.
Andrew Plato:
Tony, diagramming is useful. Don't misread my point.
It has value, but its one tool in a big kit.
Tony Markos:
We disagree on priorities.
Tony Markos
__________________________________
Do you Yahoo!?
Check out the new Yahoo! Front Page.
www.yahoo.com
ROBOHELP X5 - SEE THE ALL NEW ROBOHELP X5 IN ACTION!
RoboHelp X5 is a giant leap forward in Help authoring technology, featuring all new Word 2003 support, Content Management, Multi-Author support, PDF and XML support and much more! View an online demo: http://www.macromedia.com/go/techwrldemo
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -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.
