RE: Using the STOP methodology

[david -dot- locke -at- amd -dot- com]

STOP isn't a theory anymore. It's done for almost fifty years. I've done it
many times, and the manuals are more maintainable over product lifecycles
than linear text. If you have to document before the product is finished,
STOP works. STOP doesn't really create any overhead. I never worried about
spread decisions. I had three sizes.  I never used anything larger than a
two-page spread. If some topic got too big, it was split up and an intro
topic was written to provide linkage. 

It doesn't matter to me, the first document in whatever form, linear or
modular, help or print, will require a template, and a style hierarchy. If
the client wants to change the fonts, fine make one style change and the
entire document will change. What can't change is page orientation. Content
that fits on a landscape page will not fit on a portrait page. I've had
management flip on that decision after 200+ pages. The decision was made on
the basis of a prototype at the beginning of the project. 

The monopolies spend a lot of money to create the expectations surrounding
documentation, and it seems that management doesn't respect those
expectations thinking they have the same advantages the monopolies do. The
fact is that the monopolies can ignore customers. Your average software
startup cannot. Why do the monopolies create these expectations? To create a
market barrier that keeps out startups when the startup fails to satisfy the
expectations. Satisfaction becomes an issue of a checkbox in some IT
trade-paper review. 

If you don't have the staff to create documentation, get more staff. I've
been in your shoes, and I was creating STOP documentation at the time. My
board approved the hiring of two additional TWs, but the local manager
didn't want to and stonewalled.

There is more to STOP than page sizes. The hardest thing is the task
analysis, which should be communicated before coding is done, and it should
be part of SDK documentation. One day maybe there will be markets for
components/workproduct in our business, but we aren't there yet. 

ACM SIGDOC gave Ed Weiss their highest award for his work on STOP. You don't
get that for an unvalidated theory. But people's opinions on STOP and
modularity have to do with what discipline the TW comes out of. Engineers
and CS majors love STOP. The people I've met that came out of writing degree
programs hate STOP and modularity. Both sides have valid reasons. If you
don't like STOP, you'll do everything you can and ultimately you won't do
it. 

But, whether Horton is right about online being different, I have been the
victim of the lack of treatment variation across a documentation set.
Document sets that maintain a single treatment don't work if they don't work
the first time. Having the same text in the user manuals, help, training
manuals, and other assistance content is no help at all if that text doesn't
do the job. With different versions you might actually overcome the failure
of the first discussion. 

Who remembers Interleaf's effectivity feature?

David Locke


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

A landmark hotel, one of America's most beautiful cities, and 
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  http://ieeepcs.org/2001/

  +++  Miramo -- Database/XML publishing automation.  See us at  +++
  +++  Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion  +++
  +++ More info: http://www.axialinfo.com  http://www.miramo.com +++

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.