Re: Writing structured content [recap]

[Troy Klukewich <tklukewich -at- sbcglobal -dot- net>]

Hi Gordon:

<snip>
I asked, specifically, about "structured writing" or "writing
for single source", I also mentioned that I'm more interested in how best to
shift a docs team from writing chapters, to writing distinct chunks of
information. 
</snip>

>From a practical training angle, I've found that structuring a legacy "chapter" into a single-sourced version can be helpful. The trick is finding a nice chapter with distinct conceptual, task, and reference topics inherently embedded that can in fact be structured. It's also great if there is some duplicate content built in, like a common warning note or a reference table that can be pulled out.
 
In my last company, we set up some training using an actual chapter. It was very challenging because not all writers of this reasonably large company could analyze the content domain and figure out what to single-source.
 
A fellow manager suggested in the future taking something more generic and simple, like documenting a toaster! I would seriously consider it.
 
I just finished giving a DITA plus Epic demonstration to my product group in San Francisco last week. I took a large, well-known chapter and showed how I broke it down into structured topics, then rebuilt the content with a ditamap. I even threw in an alternate ditamap structure and a relationship table with alternate links to demonstrate the flexibility of the system. I then generated online Help, HTML, PDF, and Word builds to show how it all looked in the output.
 
Fortunately, the legacy chapter lent itself to many small conceptual topics, which is why I selected it. Though, I had to fake out some duplicate content like a warning note to demonstrate the single-sourced content references, plus add some task and reference material. It did the trick and the presentation was successful.
 
There is no doubt about it. The hands-on demonstration and training angle is essential when moving to structured documentation and single-sourced solutions.
 
Troy Klukewich
Information Architect
Oracle

----- Original Message ----
From: Gordon McLean <Gordon -dot- McLean -at- GrahamTechnology -dot- com>
To: Troy Klukewich <tklukewich -at- sbcglobal -dot- net>; techwr-l -at- lists -dot- techwr-l -dot- com
Sent: Friday, June 22, 2007 12:28:45 AM
Subject: RE: Writing structured content [recap]



<snip>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -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%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

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