TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
------------------------------
Bill Lawrence asks:
But why is everyone so insistent on WYSIWYG for technical documents?
------------------------------
I don't think anyone mentioned this, but there are times when all that "extra" markup gets in the way. We're using XML for the navigation tools in our online help. These files are getting pretty darn big and it's getting more difficult to find some bit of information that we need to get at to change or edit. Granted, we're using DW to work in our XML because most of the help is XHTML pages. DW does color code various kinds of data, but still, the markup gets in the way. It would be nice to be able to simply look at the content and edit it without having to sift through the code. Heck, an output without tags and nothing but paragraph breaks would be just peachy. Anything to make it easier to hide the code and see just the content.
This is coming from someone who sometimes wishs my powers of visualization were not so...creative...and who prefers to work with, and even enjoys working with, code and markup directly.
I would think that the Writers (note the capital W as used in another post) out there would be used to writing without format.....I mean, a manuscript is about as boring a format as you can get, no font changes, no styles, no bolding, no italics, blah blah blah. Just 12pt Courier, double space, two spaces at the end of a sentence (hehehe), and one inch margins all around. Pretty straight forward and it looks like something written in a text editor, and in fact some markets request text files for electronic submissions. So this notion of writing without worrying about format shouldn't be new to the Writers out there.
------------------------------
Geoff Hart wrote:
where we have design skill and time to use it, why shouldn't we?
------------------------------
You do use those design skills. When you first set up the template and when you tweak it as you produce more content.
------------------------------
Geoff Hart wrote:
*My first experience with single sourcing: a GM car owner's manual in
which several chunks of text had clearly been taken from the manual for
an entirely different vehicle and were clearly irrelevant to my
vehicle.
------------------------------
This isn't a problem with format though. This is a problem with how the template was set up (only part of xsl is about font sizes, colors, etc). If this manual truly was single-sourced, then the mistake was probably one of marking those paragraphs to be included when they shouldn't have been. This could have been a mistake made by the person who wrote those paragraphs, or it could have been a mistake made by someone else somewhere else in their production cycle.
------------------------------
Geoff Hart wrote:
Last but not least, do a final pass ("proofreading") to spot "layout" problems. No professional publisher eliminates the proofreading stage for print publishing. Why do we believe it could be eliminated for online publishing and single sourcing?
------------------------------
Do we believe that? I don't. If someone suggested that then I think they were hitting the happy juice a bit too much. :-)
------------------------------
Mailing List wrote:
Suddenly, you want to take away part of their jobs,
a part that they might have enjoyed. "You are a cog.
We have other specialist cogs who do what you formerly
did. Confine yourself to single-function cog-ness,
and like it. Have a nice day."
------------------------------
Eh? How does forcing a writer to concentrate on writing, and not formatting, confine said writer to "single-function cog-ness"? We're talking about technical documents here, not "War and Peace" and not the Mona Lisa. This statement seems to suggest, and please let me know if I'm wrong, that enforcing a style guide would also confine someone to single-function cog-ness. Because when it comes down to it a well design template (and the necessary transformations) is nothing more than a style guide that the writer MUST use. There's no fudging allowed because of the nature of the beast. But then again, a good template, much like a good style guide, should be flexible enough to accomodate unusual cases when they do arise.
------------------------------
Mailing List wrote:
I've never gone more than two releases of a doc set without running up against something that's broken, or that no longer serves the updated needs.
------------------------------
Exactly, and if your content is separate from your template your output would be easier to update in order to accomodate those changes. This, of course, depends on how well you thought out and designed your xml.
I think everyone should check out a site called CSS Zen Garden.
Why? Because it provides an excellent example of divorcing content from format. It doesn't use XML but rather some cleverly design HTML along with CSS. There is no transformation going on in these pages, it's straight format changes. This should give you an idea of what's possible when you separate content from format.
I've also finally started working on moving my entire site over to XML (sorry if that caused anyone to cringe hehe). I'm starting with the glossaries. When I've got the code working for Netscape, I'll post a link here. Which is actually a nice segue into a slightly off-topic question I have about client-side transformations in Gecko. If anyone has any experience in this area, I need to ask you a question. Please contact me personally so as not to bore those who could care less. :-)
SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content
Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo
>From a single set of Word documents, create online Help and printed
documentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more. http://www.doctohelp.com
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.
