One of the most recent developments in web page design has been the introduction of “long form” web pages. Will we also see the long form approach used in Help, or perhaps start to influence the way some Help pages are designed?
Editor’s Note: This post has been written by Dr. Tony Self of HyperWrite. Tony will delivering DITA training during October at Cherryleaf’s training centre in London.
In the field of technical communication, an argument crops up from time to time saying that technical communicators shouldn’t have to know anything about XML, because writing is writing, and XML is coding, and never the twain should meet. Dissecting the argument, it appears that the underlying claim is “language first; technology and tools later”.
In many cases, it seems the logic gets a little lost. I have heard statements along the line of “if you can’t string a sentence together, knowing about XML elements and attributes won’t make you a technical writer”, as if those skills are mutually exclusive.
My first observation is that the debate is often poorly framed. XML is not precise enough a term; what does “knowing about XML” mean? XML is an enormous field, covering programming, writing, archeology, journalism, eLearning, spacecraft design, mathematics, chemistry, audio recording, banking, gambling, engine management, and pretty much every field of human endeavour. So in a discussion about the role of XML in technical communication, we need to define what we mean by XML. Bearing in mind that XML is principally a standard for creating XML languages, the XML languages (or applications, in XML terminology) of interest to technical communicators are probably DITA, DocBook, XHTML, SVG, MathML, and XLIFF.
You can now watch the recording of our webinar on “Towards an Agile authoring methodology”, via Adobe’s website.
Agile development is a way of managing IT development teams and projects that creates new challenges for those involved in providing User Assistance for those products.
The conversation in a meeting yesterday went somewhat “off-topic” when someone commented on the difference between accountants and pole dancers.
Their comparison might apply between Technical Authors and pole dancers, as well: that pole dancers probably do a boring job (i.e twirling around a pole day after day) that’s seen as interesting, whereas Technical Authors (and accountants) do an interesting job that’s often seen as boring.
So what can Technical Authors learn from pole dancers? WikiHow suggests a pole dancer’s success is more to do their ability to gain rapport with the customer and keep their attention, than their dancing skills. This ability to “know” your customer and gain their attention, is perhaps a useful reminder to Technical Authors to do the same with their “performance” (that is, with the deliverables they produce).
The bookshelves here at Cherryleaf are double stacked, and we’ve received another book this week to read and then store.
So it seemed like a good time to mention which books we’d advise Technical Authors to read.
This most recent book was published by XML Press, and their publications are well worth looking at. We have quite a few books from them. Some were review copies (i.e. free), and others were ones we bought.
Most Technical Authors use style guides, and both Microsoft and IBM publish style guides you should consider buying. Style guides help you make sure you’re using the right terminology. They can also help your manuals complement the big vendors’ documentation.
Cherryleaf offers a couple of Kindle books for a just a few pounds.
Specialist books like these are not cheap, unfortunately; a decent collection of technical writing books will set you back at least £100.
Which other books and authors would you recommend to Technical Authors? You can use the comments box below to share your opinion with others.
(Flickr image: Will Ockenden)
With the recent media attention on Yahoo’s announcement that it is banning its staff from “remote” working, we thought it might be useful to look at the case for and against Technical Authors working from home.
The case for allowing remote working
- They can do their jobs more productively without interruption from others. When Technical Authors are writing (which is approximately 50% of their time), it can often help their concentration if they can work in a distraction-free environment.
- There’s less need for office space and related costs (telephones, desktop computers etc).
- Staff may be less stressed. Brad Harrington, executive director of the Boston College Center for Work & Family, claims people who work from home tend to have less stress and are more productive, partly because they don’t invest time and money in commuting, and they can have a better work/life balance.
- You may get more flexibility over staff availability. Without the need to commute, staff may be more willing to work out-of-hours.
- You have a wider pool of people interested in your vacancies if you can offer some flexibility in working hours and location.
The case against allowing remote working
- You’re more likely to build up a company culture if everyone is working in the same space together. This is particularly important for start-up businesses.
- It’s easier to network with others. These contacts could boost your careers in the future.
- It’s easier to monitor the work staff are carrying out.
- It’s can be faster to make decisions (as you can carry out impromptu meetings).
- According to Marissa Meyer, face-to-face meetings boost the quality of decisions and business ideas:
“Some of the best decisions and insights come from hallway and cafeteria discussions, meeting new people, and impromptu team meetings.”
Being a Technical Author is one of those roles where remote working can work well. However, it’s best to be able to have both options available – to have people who can come into the office within a short space of time, should there be an emergency. There’s a great deal of value in meeting people face-to-face, and to be part of a company culture (especially within startups), but it can help enormously if you can write in a distraction-free environment.
If you do work from home, you need to have a productive working environment, and be able to be self-disciplined.
What’s your opinion?
You can use the comment box below.
See also: Cherryleaf recruiting services
You’ll find we’ve added a new training course date on our Web site for our Trends in Technical Communication Workshop – Advanced Technical Writing Techniques.
Our latest post for the STC’s blog has been published today – Letter from the UK: The Dark Art of Persuasion.
The reason why Science and the dark art of persuasion interested me, was because we’re noticing the techniques of persuasion appearing in some Web-based Help. Indeed, we cover some of these techniques in our advanced technical writing course. So, although the debate was on what scientists should know about persuasion, and whether they should ever use these techniques, it seemed likely that the information would also be relevant to technical writers.