Real Value??

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

Another round on the old "structured" vs "not structured"

Let's get rid of all the "my tool is bigger than your tool" arguments and look
at the core issues to this never ending debate of structured documentation
systems.

Regardless of the tool used, technical documents must be:

1) Technically accurate
2) Readable (a generic term for "tailored for the reader")
3) Interesting

That said, the ultimate question is: will a XML/DTD/whatever system make the
documents better? 

>From what I have read, large documentation systems can help on accuracy and
possibly readability. What I have yet to see is how these systems have any
impact on making documents more interesting.

I have distilled the megabytes of text being generated on this topic. According
to Dan and Tim, complex documentation system have the following benefits:

1) Reusability / single sourcing
2) Configuration management (or change management)
3) Eventual return on investment (ROI) in time savings.

However, these system have inherent faults:

1) Rigidity
2) Tremendous upfront expense
3) "Non-writing" overhead

So the question is: does a company want to bind themselves to a rigid,
expensive system that requires extensive "non-writing" maintenance overhead to
get reusability, change management, and eventual ROI.

Let's place tech writing groups into three categories to analyze this benefit:

1) Basic:  2 - 5  writers, 20 to 50 documents produced per year. 75% generation
of new docs, 25% maintenance of old docs. Docs are very prone to change.  The
group is mostly savvy writers who work independently. 

2) Intermediate:  5 - 20 writers, 50 to 200 documents produced per year, 50%
new doc generation, 50% maintenance docs. Many docs are static with little
change, but new stuff is still in flux. The group is a mixture of independent
writers and corporate drones. 

3) Large: 20+ writers, 250 to 500 documents produced per year, 25% new doc
generation, 75% maintenance. Lots of basically static documents, some new stuff
is in flux, but this is minor.  The group is mostly corporate drones with few
independents. 

Now, let's ask ourselves, which groups would REALLY benefit from a structured
XML/DTD thing? 

Basic: No way. Too small. The expense would crush such a group. Not to mention
the fact that structured systems are not well suited to new doc generation.
This group would be better off setting very basic standards and hiring very
capable writers allowing their group to grow and mature naturally. Reliance on
savvy, independent writers basically precludes any hope of centralizing the
department. 

Intermediate: Possibly. With a larger percentage of maintenance docs, there is
a powerful argument to standardize those docs for quick turn around. Such a
group may benefit from a limited change management system. Although the drones
should be put in charge of the system while the independents do all the
writing.  A full structured system would probably be excessive.  

Large:  Probably, if they can stomach the cost.  With such a huge margin of
maintenance documentation, a large structured system becomes almost a
necessity. Also, with lots of initiative-lacking drones, large complex systems
with lots of rules and regulations give the drones a sense of purpose in life. 

Thus, the tipping points for a rigid documentation system are:

- Scope: Does your group have a ton of documents? 

- Static vs dynamic: Are those docs essentially static or do they go through
massive changes. 

- New vs. Maintenance:  What percentage of your docs are "new" versus merely
updates to existing docs?  

- Personnel: Are you a group of free-wheeling independents who don't need no
stinkin' rules or a pack of committee-philes who need a crystal clear path from
ignorance to tepid achievement?  

My conclusion: 

If you have money, time, drones and a ton of documents, call Tim and Dan. I am
convinced they can make your XML/DTD thing work. 

If you have no money, no time, and are basically about to be kicked in the ass
by the CTO for not having decent docs - call a freewheeling independent (like
me) who can hammer the docs back into shape. 

However, one last point: interesting documents do not come from organization.
Only a capable writer who comprehends the subject matter can write in an
interesting manner. Thus, no DTD/XML thing can make your documents more
interesting. You got to have a clue to do that.

Andrew Plato

No butterfly ballots here: http://members.home.com/aplato 

__________________________________________________
Do You Yahoo!?
Yahoo! Shopping - Thousands of Stores. Millions of Products.
http://shopping.yahoo.com/

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators 
Publications Management Clinic, TECH*COMM 2001 Conference, and more 
http://www.SolutionsEvents.com or 800-448-4230

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