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.
--- Dick Margulis <margulisd -at- comcast -dot- net> wrote:
You're not happy with the notion that "structured
writing" is a
loose synonym for analysis.
Tony Markos responds:
If structured writing (formatting considerations
aside) is the same or nearly the same as analysis,
then the term serves no purpose other than to create
confusion. We are writers; we should be about
clarification - not adding to the IT worlds confusion.
Dick, regarding your (below) steps in doing analysis
(and some formatting), thanks! Finally, some
specifics! Your right, it is not brain surgury.
Dick Margulis:
Okay [regarding Tony Markos request for specific steps
in what is erringly called "structured writing"},
let's restrict this to task-based user instrucdtions
(your example).
1. Access the functional spec.
2. Test whether or not the functional spec is linear
(can be read in an unambiguous order from beginning to
end). If it is not linear, linearize it.
3. Copy the structure (outline, based on headings)of
the functional spec to a new document.
4. For each functional requirement, exercise the
product to obtain the desired results. If you cannot
figure out how tooperate a necessary feature to obtain
the desired results, refer to the design spec for that
feature. If the design spec does not match thefeature,
inquire of the individual (SME) who is responsible for
the construction of the feature how it operates.
Write down each of the steps you follow to obtain the
desired results.
5. Consider whether you may have used unnecessary
steps or whether you might have performed the steps
in a more intuitive
sequence. Test all such variations until you obtain
the simplest
(shortest) sufficient sequence of steps.
6. Consult a style guide to determine the preferred
way to express each step and write the step according
to the guide.
7. Label each paragraph in the procedure with the
style tag named in your style guide.
8. Publish a draft.
9. Circulate the draft for review.
Etc. Shall I go on?
__________________________________________________
Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
