Re: Structuring Documentation

Subject: Re: Structuring Documentation
From: Dick Margulis <margulisd -at- comcast -dot- net>
To: Tony Markos <ajmarkos -at- yahoo -dot- com>
Date: Tue, 13 Dec 2005 11:37:14 -0500

Tony Markos wrote:

Dick:

I have not been asking for an algorithmic way to do
writing. To me, asking for such is nutso.

You have been asking, and it's not nutso (well, it's economically impractical, of course; but there is no logical impediment to the eventual automation of a lot of tech writing tasks).

You have been asking for a definition of structured writing. You're not happy with the notion that "structured writing" is a loose synonym for analysis. We know that writing is a process, and a structured process is, for all practical purposes, an algorithm. So I say that's what you've been asking for.

Analysis exists - specific steps can be identified for
doing such. Writing also exists - you are reading
some. But I have found no evidence that structured
writing exists as a seperate entity from these two.

People teach writing. Some people teach it more effectively than others; some students pay more attention than others; some people are not wired to be writers. Hence we have a wide range of writing abilities expressed in the population; but that does not mean that nobody can teach how to write, especially if we're restricting the discussion to the production of task-based user instructions, which are pretty formulaic, after all, by people who want to learn how to do the job. It just means that we have to take externalities like talent and attentiveness to detail into account when selecting people to be tech writers.




Dick, you mentioned Logic 101 to me before. As you
are a fan of logic, let me ask you: What are the steps
to structured writing? (Please do not say do analysis
and then write.)

Okay, 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 to operate a necessary feature to obtain the desired results, refer to the design spec for that feature. If the design spec does not match the feature, 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?

What's so confusing about this? It's a straightforward sequence of steps that, iterated as appropriate, will result in the structured document we want as output. It's not brain surgery.


Dick

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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: Tony Markos

Previous by Author: Re: Structuring Documentation
Next by Author: Re: Smart answers and useful answers
Previous by Thread: Re: Structuring Documentation
Next by Thread: Re: Structuring Documentation


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


Sponsored Ads