Re: Single Sourcing

[Megan Golding <mgolding -at- secureworks -dot- net>]

Diane Evans is interested in a single source solution for producing the
following:
> a brochure, a white paper, a
> detailed spec (a technical spec with the programming missing, just the
> names
> and explanations of the API calls), and a PowerPoint presentation

If you're up for a challenge and a good learning curve, I highly
recommend DocBook. DocBook is a Document Type Definition (DTD) that
allows you to write text files using special tags and then process the
source for various output types. I've produced HTML files, PDF
documents, and am aware of the ability to output slides (presumably for
PowerPoint-type programs).

Since switching to DocBook, I've found my documentation is highly
reproducible. Recently, for example, I needed to alter an existing
manual for a new hardware platform, but much of the content remained the
same. In addition, the marketing team suggested I change the paper size
for the new manual. I made the content changes in a few hours, altered a
stylesheet parameter for paper size, and created a new document in PDF
and HTML.

DocBook is platform-independent and the tools for processing documents
are available for both Windows and Unix systems. DocBook and associated
tools are open source and free.

A word of warning, though, DocBook is not a word processor. You won't be
using a WYSIWYG interface. (Still reading? I'm impressed...usually that
scares most folks away.)

Check out my favorite resource for a DocBook introduction:
http://www-106.ibm.com/developerworks/library/l-docbk.html

[pause, while I review what I've written so far]

Now that I've looked back on your needs, I have to ask myself -- is
single-source best for these disparate document types? Brochures are
usually layed out in page layout programs like Page Maker; white papers
are usually handled in a word processor or markup language like DocBook;
the API/spec is typically done in an automated fashion using commented
code and a tool like Javadoc or doxygen; and Power Point presentations
are, well, usually handled in Power Point.

Good luck with whatever you choose!

-- 

Megan Golding (mgolding -at- secureworks -dot- net)
SecureWorks, Inc.

Women who seek to be equal with men lack ambition.
	-- Timothy Leary


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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