atw: Wordsmith or technical writer? (WAS RE: Re: XML - a requirement for a TechWriter looking forwork?)
- From: "bja" <moo-man@xxxxxxxxxxxxxxx>
- To: <austechwriter@xxxxxxxxxxxxx>
- Date: Fri, 12 Sep 2008 11:35:46 +1000
I have bitten my lip long enough.
Spoken like a true wordsmith Stephen but there is more to a document than
mere words (as important and critical as they are).
Unfortunately, someone has to understand the back-end of documentation to do
silly things like understand how the documents need to be put together, how
best to create the templates required, what tools are needed to make the
task as efficient and cost-effective as possible, what processes should be
put in place to best produce each document, how to fix issues with size,
images, legacy material, etc ... the list is very long.
Quoting Shelly or understanding the difference between 'your' and 'you're'
probably won't help, and I'd suggest that to be a technical writer, you need
to be good at language AND have 'technical' documentation skills. To me,
this where we can distinguish between technical writers and technical
communicators, wordsmiths and the like.
There is nothing wrong with being a highly skilled grammarian but this, in
itself, does not make you a 'technical writer' and that was the thrust of
the original thread.
I always sigh with exasperation when other supposedly senior 'technical'
writers cannot even align objects properly in a Visio drawing, do not know
when to use a table or have problems aligning page numbers in a ToC (to name
but a few). I feel like reaching for a clean nappy every time they come
running to the water cooler looking for help.
And as for your statement, "Manipulating and formatting the written document
is publishing - something that any brainless twat can learn given time and
sufficient punishment", this clearly shows you are ignorant of the process
and should stick to prose (or have a technical writer create a document for
you so that you can tweak it).
Anyway, 'nuff said from me.
My 0.03.
Cheers,
Bruce
_____
From: austechwriter-bounce@xxxxxxxxxxxxx
[mailto:austechwriter-bounce@xxxxxxxxxxxxx] On Behalf Of Stephen Nason
Sent: Friday, 12 September 2008 9:19 AM
To: austechwriter@xxxxxxxxxxxxx
Subject: atw: Re: XML - a requirement for a TechWriter looking forwork?
I think some of you are confusing the art of writing with the act of
publishing.
You don't need to know all that dull code cutting stuff to be a good writer.
And good writers are what employers want, not
IT bods that can mix and match exotic acronyms with the nerds around the
water cooler.
Good writing is about transmitting ideas and concepts from one human brain
into others with ease and grace. It is a talent that in many ways can't be
learned. Manipulating and formatting the written document is publishing -
something that any brainless twat can learn given time and sufficient
punishment. If you are spending your time doing a lot of XML then your not
a writer - just another backroom boy. I agree with Geoffrey that a
potential employer wants writing skills at top of list. Can flick the
drafts to some IT nerd to format, publish etc.
Funny thing how once some programming tool has been learned, it becomes part
of a snobbish upmanship process. There was a time when DOS knowers stuck it
up Mac users for clicking icons instead of writing command code. The XML
argument is much the same.
Writing is, and always has been, about communication folks, not technology.
Now where's that bloody quill....
Steve
----- Original Message -----
From: Christine Kent <mailto:christine_kent@xxxxxxxxxxxxxxx>
To: austechwriter@xxxxxxxxxxxxx
Sent: Thursday, 11 September 2008 3:01 PM
Subject: atw: Re: XML - a requirement for a TechWriter looking forwork?
U boys just ain't gettin' it, R ya? She ain't using XML, she using Word
2007!
I bin usin' 2007 long time now, and I don need to do what you say to do boy,
cos I done it all thru 2007. It rescue b******* files good for me.
Mebbee will need to de-zip file one day - then I fin' out how on web. Till
then, 2007 good muff!
Your tool not good nuff?
CdumbdumbK
-----Original Message-----
From: austechwriter-bounce@xxxxxxxxxxxxx
[mailto:austechwriter-bounce@xxxxxxxxxxxxx] On Behalf Of
peterm_5@xxxxxxxxxxxxxx
Sent: Thursday, 11 September 2008 2:34 PM
To: Judith.Bluhm-Brown@xxxxxxxxxxxxx; austechwriter@xxxxxxxxxxxxx
Subject: atw: Re: XML - a requirement for a TechWriter looking forwork?
You sure of that ? You might be surprised.
Just as SVG is an XML standard for vector graphics, you should know
that .docx (Word 2007) is a zipped file containing a collection of
XML files...
Sooooo.... if you're using Word 2007, you're using XML, one way or
another.
And IF you don't have Word 2007, and have one of those .docx files
that Word 2003 won't read for you, it might be handy to know, in an
emergency, you can:
1. rename the .docx file to .zip
2. unzip the file
3. browse thru the XML files, and get an extract of basic information
from a file you otherwise can't read.
Helps if you know what to look for if you're in a hurry...
Like how to jump start a car with a clutch... :-)
-Peter M
>
>
>---- Original Message ----
>From: Judith.Bluhm-Brown@xxxxxxxxxxxxx
>To: austechwriter@xxxxxxxxxxxxx
>Subject: RE: atw: Re: XML - a requirement for a TechWriter looking
>forwork?
>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-a
>dmins@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:
- » atw: Wordsmith or technical writer? (WAS RE: Re: XML - a requirement for a TechWriter looking forwork?)
