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.
Subject:Re: Giving up on XML From:"Sean Hower" <hokumhome -at- freehomepage -dot- com> To:<techwr-l -at- lists -dot- techwr-l -dot- com> Date:Tue, 20 Mar 2007 07:44:32 -0700
> Mike Starr
> I do think that, in spite of not having
> been created by an "official" Structured Document Authoring Tool?, it
> could still actually be a structured document. If it walks like a duck...
I don't know if this is true. There's a difference between creating styles with the intent of using those styles to provide a structure, and defining the structure itself. This gets back to separation of content and format. So, if it walks like a duck, it could still be a goose, a chiken, or even a turkey. Turkey walk pretty funny after all. ;-)
> There should always be a mechanism in place for situations that weren't
> anticipated when the style guide/DTD was created. Even the best style guide > needs to be overridden once in a while. That's the value of an experienced > writer.
Of all people, I would certainly agree with you. But this sort of statement opens up a slippery slope. Perhaps it would be better to say that style guides should be updated to reflect new needs, not "overridden."
> But just out of curiosity, if one skips a level, is that inherently
> evil? Isn't the resulting document still intact with respect to the
> heirarchy?
No on both counts. If your goal isn't to create a structure, then skipping levels isn't a bad thing. If you establish a structure then override it, then no the document is not intact in respect to hierarchy. This might be a bad thing if the output depends on that structure, for example TOCs or perhaps a bit of scripting. It could also be a bad thing if you are working with more than one person and the final documents must be consistent in respect to structure and format. I would submit that if someone is skipping the hierarchy, that person needs to examine his/her writing to understand why it is necessary to override the hierarchy. This isn't just a matter for XML, it's about documentation methodology.
> Gene Kim-Eng
> If XML is just a language there's no reason why it shouldn't be possible > to use it in tools that create unstructured documents as well.
Well, it is possible to use XML without a schema or DTD. There's nothing that says you have to. The DTD/schema is there to enforce the structure. So technically, it is possible. Here's a couple of examples:
But, to be frank, the xml that this output uses is more of a dataset than a document. Still, though, the point still applies.
> Paul Pehrson wrote:
> Sure, you can create your own XML-based markup language if you want, but
> it seems to me that in the end why bother when there are vendors that will
> create tools that allow you to work with XML (with all the benefits of
> using XML), and never have to worry about the underlying code? I suppose > it is a case of picking the right tool that allows you to accomplish your > end goal, which to me is more important than the specific method for
> achieving that goal.
I didn't know that Flare did this. I'll have to check it out. :-) When I was getting into XML, there were very few vendors that did....there were a lot that made the claim, but they really didn't do what they said they did.
Gene Kim-Eng wrote:
> I want the languages used under the hood of my authoring tools to be like
> the heating elements in my toaster, something that works for me
> on a daily basis without my having to pay any attention to it at all.
And now here-in lies, I believe, a core difference between "early adopters" and other users. Early adopters don't mind getting under the hood. In fact, they crave it. All others just want to get their work done. There's nothing wrong with either approach. ;-) The last time I really dug into authoring with XML it was still something gear mostly towards the "early adopter." I don't know if it's still that way.
> Ned Bedinger wrote:
> ...and IMHO human consumers and writers of documentation do seem to
> prefer documentation that has not been fully elaborated with empty-but-
> logical structure.
I totally agree with you, empty but logical structure is bad. BUT, if your (general sense and not you specically) documentation is coming out this way then you're structuring your information wrong and you need to reexamine your approach. We're not talking about complex hierarchies here, we're talking about simple, three- to four-level structures. If you (in general) can't follow that structure, you need to rewrite.
> So we created a separate
> structure for command/function sections and styled
> its title to distinguish it from standard head3s
> with a smaller, monospace font.
A perfectly logical and responsible thing to do. The guide is a guide and should adapt as needed. If this were an XML solution, you might have to update your DTD.....or you could get creative with the XSL.
> If Mike works on his own as a sole writer at
> a company and the company is happy with his
> aesthetics and his professional judgments about
> structure, then he's right that his tools and
> environment are working fine for him. But in
> an environment where documentation sets are
> being produced by numerous writers and text
> potentially could be reused in different outputs,
> I think that consistent structure and appearance
> is an important benefit to be gained by using a
> structured authoring language.
And therein lies a factor that one should consider when determining whether to go with XML. I've said it before, and I'll say it again. XML is not right for all environments and all needs. :-)
Cheers. :-)
********************************************
Sean Hower - communications specialist http://www.sean-hower.com
_____________________________________________________________
Create your own web site for FREE at http://www.freehomepage.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList
Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help & Manual: http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
