atw: Re: XML - a requirement for a TechWriter looking forwork?
- From: "Judith Bluhm-Brown" <Judith.Bluhm-Brown@xxxxxxxxxxxxx>
- To: "austechwriter@xxxxxxxxxxxxx" <austechwriter@xxxxxxxxxxxxx>
- Date: Thu, 11 Sep 2008 10:19:22 +0800
Well said, Geoffery. I'm a very successful technical writer (i.e. I get paid
very well) and I don't use XML.
-----Original Message-----
From: austechwriter-bounce@xxxxxxxxxxxxx
[mailto:austechwriter-bounce@xxxxxxxxxxxxx] On Behalf Of Geoffrey Marnell
Sent: Thursday, 11 September 2008 10:13 AM
To: austechwriter@xxxxxxxxxxxxx
Subject: atw: Re: XML - a requirement for a TechWriter looking forwork?
Tony,
As an academic yourself, you know full well that not all skills that might
be useful in a profession are of equal value. Grammar and spelling (and,
more importantly, communicative efficacy) are of fundamental importance in
technical writing, of far greater importance than knowing any particular
tool or knowing any particular tagging methodology. The equation is simple:
without knowledge of grammar and spelling, you won't make it in technical
writing. However, without knowledge of HTML and XML, you can make it in
technical writing, and will be able to do so for decades to come (just as
have for the last 400 years of technical writing).
I can't make sense of your comment that "without spelling and grammar, you
could produce a decent document". Read literally, that is nonsense. A
document replete with misspellings and mangled syntax would never be a
decent document. Or are you saying that you could still produce a decent
document without relying on a spell checker and grammar checker. That's
obvious, but it proves nothing. Any writer worth their keep knows not to
rely on grammar and spelling checkers.
As for accessibility issues, of course technical writers (or at least those
who produce online deliverables) need to know the issues here. But knowing
the issues and knowing the under-the-bonnet stuff are chalk and cheese. You
set a percentage rather than a fixed point size (to take your example) by
choosing one option from a menu in Dreamweaver. It's that simple. I don't
need to know anything about the underlying tags and attributes to do this. I
just need to know what the accessibility issues are and where the
appropriate menu options are in Dreamweaver.
Maybe we are merely disagreeing about the extent of HTML and XML knowledge
needed. Yes, of course, someone building a web page is no doubt better off
knowing that the tagging system behind it is called HTML (as this might help
them narrow down searches if they get stuck). But they can happily get by
without knowing anything about the underlining tags. (I can choose BOLD from
a Dreamweaver style dialog without needing know that <b> and </b> tags will
then encase my selected text.)
And it's the same with XML. Yes, knowing what a DTD, element and attribute
is useful, but I don't need to go to XML school and learn all about the
under-the-bonnet stuff if all I'm going to do is point my document at a DTD,
and then select elements and attributes from GUI dialogs. (We did that years
ago with SGML without needing to know the nitty gritty of SGML tagging.)
If you intend your career in technical writing to branch off towards that of
a documentation technician, by all means learn all that stuff. But for Nikki
Ward, and for most of us, it is just overkill.
Cheers
Geoffrey Marnell
Principal Consultant
Abelard Consulting Pty Ltd
T: (+61 3) 9596 3456
F: (+61 3) 9596 3625
W: http://www.abelard.com.au
-----Original Message-----
From: austechwriter-bounce@xxxxxxxxxxxxx
[mailto:austechwriter-bounce@xxxxxxxxxxxxx] On Behalf Of Anthony Self
Sent: Thursday, 11 September 2008 11:27 AM
To: austechwriter@xxxxxxxxxxxxx
Subject: atw: Re: XML - a requirement for a TechWriter looking forwork?
A question for you, Geoff...
What's your position on the necessity of a technical writer to spell, or to
understand grammar? Is that a "nice to have" or a "requirement". Following
your argument that a software tool can hide those technical nasties like CSS
and HTML markup from the user, surely FrameMaker, with its grammar checker
and spell-checker can also hide the technical nasties of spelling and
grammar from the user.
I would think that without spelling and grammar, you could produce a decent
document. Nothing flashy, not particularly good, won't win a Booker prize,
but it's only for a dull and dreary policy-and-procedure intranet with no
budget!
With Dreamweaver skills but no interest in HTML and CSS principles, writers
usually produce content that doesn't comply with accessibility requirements.
A simple case in point... if you style your CSS using point sizes instead of
percentages, the text on your page can't be displayed in a larger or smaller
text size by people with poor eyesight. We're meant to be professional
communicators, and that means having more than a superficial understanding
of the "tools" we use to communicate, including spelling, styling, content
structure, authoring tools, writing methodologies and delivery formats.
Obviously, I think that knowledge of spelling and grammar is a requirement
for a technical writer. I also think that an understanding of those XML
principles that apply to technical communication is a requirement for a
technical writer wanting to develop a career in the industry.
In explaining how little a writer needed to know about XML, you used the
terms DTD (EDD), blocks, elements, attributes, and content rules. Those
following this thread who don't have any idea about XML will realise that
these terms and concepts are critical to understanding what we're on about!
(To pre-empt another argument, it's irrelevant whether XML "invented" those
concepts. They are still XML concepts.)
Cheers
Tony
>>> "Geoffrey Marnell" <geoffrey@xxxxxxxxxxxxxx> 11/09/2008 10:37 am >>>
Thanks Peter,
We seem to be in complete agreement. Taking into account all your
conditional statements, it seems that we have both answered Nikki's original
question the same way: knowing XML is not "becoming part of a REQUIREMENT
for a Tech Writer".
Further, you write "If you really want to know how to use structured
documentation based on XML, it really is very important to know a bit about
what's going on under the bonnet". This is not the case at all. There are
companies who use structured authoring merely to instil structural
discipline on their authors. A DTD (or EDD in FrameMaker-talk) regulates
what blocks of text can go where, forcing the authors to follow a predefined
set of content rules. Saving the file as XML is another step altogether, and
is not necessary. (That is, you can save a structured FrameMaker document as
a FrameMaker file. You are still doing structured authoring, and you can do
so without knowing a single thing about XML. (Yes, you need to know about
elements and attributes; but these are general concepts, not tied to XML.
They were part of structured authoring well before XML surfaced.)
But even if we go one step further and save our structured documents as XML,
how much about XML do we really NEED to know? If I'm just going to open the
file again at a later date, I just point FrameMaker at it and it opens. If
it is going to be repurposed by some other author, I just check it in to
some CMS or other repository: no XML skills needed here. In this scenario,
the XML code thus generated, and the deeper XML-based application routines,
are of no concern to me.
Let me repeat from an earlier message in this thread: knowing what XML is is
useful (and knowing what structured authoring is is even more useful,
bearing in mind that the two are not inextricably linked). But that doesn't
mean that knowing this stuff is a *necessary* requirement for working in
technical writing. My concern with Nikki's original post was that a whole
lot of young readers relatively new to our profession might get the
impression that they will never break into technical writing unless they
learn XML. And that's just bollocks. Even if every single documentation
project were to be based on structured authoring (which will never be the
case) authors would still be able to get by without any detailed knowledge
of XML. Structure is structure; what comes out at the other end is something
different. If we don't accept that then you'd have to accept that SGML and
XML are one and the same.)
Let's extend this even further: most non-FrameMaker XML-generating workflows
require XSLT or XSL-FO to render the raw tagged text as professionally
formatted documents. It's professionally formatted documents that technical
writers are expected to deliver. So are we going to say further that knowing
XSLT and XSL-FO is also becoming a necessary requirement for a technical
writer. Again that's bollocks. Just as we left the pain of learning HTML to
the propeller heads who created GUI editors, we (that is, technical writers)
will leave the pain of text rendering to the propeller heads (and those
dabblers in technical communication who are probably better described as
"documentation technicians") to provide the necessary GUI interfaces for
applying format to structure. (Already in FrameMaker, by the way.)
And I still stand by my statement yesterday that you don't need to know HTML
to produce decent websites. Yes of course there are bugs in HTML editors and
numerous browser incompatibilities. And I agree that if you want to
reproduce the flashy, script-driven, multi-layered design you have in your
head then it's likely that you'll only get that with code-kludging,
precisely because of those bugs and limitations. But for every flashy,
script-driven, multi-layered design there is a thousand simple effective
websites generated by the tools I mentioned that do what they were designed
to do. Technical writers don't work as graphic artists: they don't approach
their tasks with an Australian Design Award in mind. Most of the HTML work
we get to do is dull and dreary policy-and-procedure intranets where budgets
deny us the pleasures of flashy, script-driven, multi-layered designs. And
thus we get by without needing to know HTML. All the design and styling
dialogs in, say, Dreamweaver keep us happily away from the tags and tangles
below the bonnet. Crikey, next we'll be saying that knowledge of JavaScript
is a *necessary" requirement of becoming a technical writer just because
sometimes Dreamweaver buggers up JS. Nice to have, perhaps...but surely not
a necessity. Again, I swing the conversation back to Nikki's original
question: requirement versus nice-to-have.
Cheers
Geoffrey Marnell
Principal Consultant
Abelard Consulting Pty Ltd
T: (+61 3) 9596 3456
F: (+61 3) 9596 3625
W: http://www.abelard.com.au
-----Original Message-----
From: austechwriter-bounce@xxxxxxxxxxxxx
[mailto:austechwriter-bounce@xxxxxxxxxxxxx] On Behalf Of
peterm_5@xxxxxxxxxxxxxx
Sent: Wednesday, 10 September 2008 6:48 PM
To: geoffrey@xxxxxxxxxxxxxx; austechwriter@xxxxxxxxxxxxx
Subject: atw: Re: XML - a requirement for a TechWriter looking forwork?
Geoffrey:
Nothing quite like an extended metaphor, but let me put it this way.
I don't have to be a qualified mechanic to drive a car, anymore than I have
to be a C# programmer to use some accounting software.
But if I want to be a competent driver, it helps to know:
1. which bit the engine is under (VW drivers please note) 2. which holes
take water and which take petrol 3. to use petrol in the tank instead of
kerosene, and which type of petrol 3. what to do about a flat tyre 4. what
to do about a flat battery.
And a few miscellaneous "specialised" items, even such things as what gear
to use going up a hill, and how to handle a rear wheel skid and a front
wheel skid are things that are extremely useful (and hard to follow if you
don't understand the mechanics of what's going on so you can detect a
problem beforehand).
Of course you can drive a car without really knowing all of these things.
But doing it well does seem to require a few of the above "specialist"
items. I can get in and start an engine, get a car into gear, turn a wheel,
etc for a while, and that's driving, but it's not effective driving for long
if I don't know at least something about the other "stuff".
And just as I'm going to look bloody silly trying to pull the load of a
B-double with a Toyota Corolla, it's important to know the limits of what
can be done and ideally, why those limits apply, so that I don't waste time
attempting the impossible.
If you really want to know how to use structured documentation based on XML,
it really is very important to know a bit about what's going on under the
bonnet, unless you don't mind dying wondering...
I earlier mentioned that knowing how to fix stuff (which implies knowing how
stuff works) is a handy skill to have if you want to work effectively and
economically.
That's as true with documentation tools as it is with cars.
When everything works, it's all rosy in the garden. Don't know
about your garden, but we still have aphids, bugs, washaways, soggy bits etc
in our garden. And people have been gardening for centuries.
Dreamweaver works ?
Yes, maybe. It didn't usta write valid HTML, and those of us who used it
then were grateful for any insight into how to make its output
work properly. It usually meant hacking changes in the raw HTML.
You could be a tech writer working with only plain text. Somewhere.
Used to happen. Once upon a time.
--Peter M
**************************************************
To view the austechwriter archives, go to
www.freelists.org/archives/austechwriter
To unsubscribe, send a message to austechwriter-request@xxxxxxxxxxxxx with
"unsubscribe" in the Subject field (without quotes).
To manage your subscription (e.g., set and unset DIGEST and VACATION modes)
go to www.freelists.org/list/austechwriter
To contact the list administrator, send a message to
austechwriter-admins@xxxxxxxxxxxxx
**************************************************
-----
Swinburne University of Technology
CRICOS Provider Code: 00111D
NOTICE
This e-mail and any attachments are confidential and intended only for the
use of the addressee. They may contain information that is privileged or
protected by copyright. If you are not the intended recipient, any
dissemination, distribution, printing, copying or use is strictly
prohibited. The University does not warrant that this e-mail and any
attachments are secure and there is also a risk that it may be corrupted in
transmission. It is your responsibility to check any attachments for viruses
or defects before opening them. If you have received this transmission in
error, please contact us on +61 3 9214 8000 and delete it immediately from
your system. We do not accept liability in connection with computer virus,
data corruption, delay, interruption, unauthorised access or unauthorised
amendment.
Please consider the environment before printing this email.
**************************************************
To view the austechwriter archives, go to
www.freelists.org/archives/austechwriter
To unsubscribe, send a message to austechwriter-request@xxxxxxxxxxxxx with
"unsubscribe" in the Subject field (without quotes).
To manage your subscription (e.g., set and unset DIGEST and VACATION modes)
go to www.freelists.org/list/austechwriter
To contact the list administrator, send a message to
austechwriter-admins@xxxxxxxxxxxxx
**************************************************
**************************************************
To view the austechwriter archives, go to
www.freelists.org/archives/austechwriter
To unsubscribe, send a message to austechwriter-request@xxxxxxxxxxxxx with
"unsubscribe" in the Subject field (without quotes).
To manage your subscription (e.g., set and unset DIGEST and VACATION modes) go
to www.freelists.org/list/austechwriter
To contact the list administrator, send a message to
austechwriter-admins@xxxxxxxxxxxxx
**************************************************
**************************************************
To view the austechwriter archives, go to
www.freelists.org/archives/austechwriter
To unsubscribe, send a message to austechwriter-request@xxxxxxxxxxxxx with
"unsubscribe" in the Subject field (without quotes).
To manage your subscription (e.g., set and unset DIGEST and VACATION modes) go
to www.freelists.org/list/austechwriter
To contact the list administrator, send a message to
austechwriter-admins@xxxxxxxxxxxxx
**************************************************
Other related posts:
