Changing times in technical communication 3 – The long form Help topic

New York Time snow fall article imageOne 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?

Continue reading

Writers shouldn’t code… or should they?

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. 

Code ninja tshirt flickr creative commons image by juhansoninIn 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.

Continue reading

Towards an Agile authoring methodology – webinar recording

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.

See:

Towards an Agile authoring methodology webinar recording

 

What Technical Authors can learn from pole dancers

Pole dancer Flickr creative commons image by gophotodotcomThe 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).

Which books should Technical Authors read?

Woman reading bookThe 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.

Then there are the technical writing “classics”. In this group, we’d recommend you look at books by Ron BlicqJohn Carroll, JoAnn HackosKaren Schriver and Joe Welinske.

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)

Should Technical Authors be allowed to work from home?

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

  1. 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.
  2. There’s less need for office space and related costs (telephones, desktop computers etc).
  3. 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.
  4. You may get more flexibility over staff availability. Without the need to commute, staff may be more willing to work out-of-hours.
  5. 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

  1. 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.
  2. It’s easier to network with others. These contacts could boost your careers in the future.
  3. It’s easier to monitor the work staff are carrying out.
  4. It’s can be faster to make decisions (as you can carry out impromptu meetings).
  5. 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.”

Our opinion

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

Announcement: April date for the Advanced Technical Writing Techniques course

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.

It will be held on Monday 22th April.
Continue reading

Technical Authors and the dark art of persuasion

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.

See Letter from the UK: The Dark Art of Persuasion.