RE: Value of design documents (was: New TECHWR-L Poll Question)

["David Berg" <dberg -at- dmpnet -dot- com>]

> I've worked with specs in formal language, with an explanation and
> commentary in natural language. This is very useful for a writer,
> because it
> really lets you test your understanding of the specification language
> constructs; also many implementations add features or do not support
> specific parts of a specification; this is a real good way to note this.

I strongly suspect that this is along the lines of what Geoff was
suggesting. If you explain as much of the spec as possible in natural
language, using both text and graphics, and then clarify the specifics as
needed in formal language, I believe that everyone would benefit, both
techies and non-techies alike.

Just because someone can comprehend formal language doesn't mean that it's
the most readable and usable form for that person, at least regarding the
portion of a document that doesn't have to be in formal language.

My brother is a physician. Throughout his medical training he was at the top
of his class and he had no trouble gaining admittance to top programs for
his internship and residency. In spite of the fact that he has the education
and intelligence to understand even the most advanced medical literature in
his field, he commonly uses reference books written for nurses because they
are written in a "friendlier" language that makes the information more
accessible. When he needs more advanced or specific information he still
refers to physician reference material. What a shame that more material
isn't available that offers a mix of both; a simple reading style when
possible with advanced language only when needed.

I feel that conventions that require a "scholarly" writing style often have
more to do with snobbishness and professional conceit than anything else.
And to stave off at least a few of the possible flames in response to this
statement, I recognize that specific advanced terminology is necessary in
many documents to make the meaning clear. My point is that this advanced
terminology (when it is truly needed) can be used in a writing style that is
still more accessible.

David Berg




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17)
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 
Conference East, June 4-5, Baltimore/Washington D.C. area.
http://www.pdfconference.com or toll-free 877/278-2131. 

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