Re: Structuring Documentation

Subject: Re: Structuring Documentation
From: Tony Markos <ajmarkos -at- yahoo -dot- com>
To: Dick Margulis <margulisd -at- comcast -dot- net>
Date: Tue, 13 Dec 2005 11:53:04 -0800 (PST)



--- 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-

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

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


Follow-Ups:

References:
Re: Structuring Documentation: From: Dick Margulis

Previous by Author: Re: Structuring Documentation
Next by Author: RE: Structuring Documentation
Previous by Thread: Re: Structuring Documentation
Next by Thread: Re: Structuring Documentation


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads