Writing troubleshooting topics

It’s a fair bet that the introduction of the new Troubleshooting information type into the DITA 1.3 technical authoring standard will affect how all Technical Authors write troubleshooting topics, regardless of whether they use DITA or not. That’s because the proposed elements for troubleshooting topics make good sense, and it offers a standardised approach to writing these types of topics.

According to the Oasis DITA standards committee,

Troubleshooting topics provide descriptions of and solutions or workarounds for problem situations that users might encounter. Users refer to troubleshooting information to understand what condition or event generated their problem situation and to find out what they need to do to recover from or work around a problem, or to prevent a recurrence of the problem.

The user would see a topic that looks roughly like this:
Continue reading

Why you probably shouldn’t use Word to create your policy documents

Flickr image "Holmes McDougall Employee Handbook" by Edinburgh City of PrintImagine you are an IT manager for an organisation that has been implementing new IT systems. You have now reached the point where you need to create and document the new IT policies and procedures. The organisation already has some general policies for IT in its staff handbook, but you need to provide more detailed information on how to use the organisation’s IT efficiently and securely.

For example, the staff handbook tells staff that customer information must be treated confidentially and only approved communication channels must used. The IT policy and procedures document will provide more detail  - that web email services (such as Yahoo Mail) must not be used to send customer information, because they often store a copy of the email even if you have deleted your sent message.

The best approach would be to have some sections in both the staff handbook and the IT policy document. In other words, the same content in different documents. Otherwise, staff would need to have two manuals open each time they wanted to check they were doing things correctly.

If you use Word, you’re likely to do this by coping the text from one Word document and pasting it into the other Word document. The problem with this approach is that when you make a change to the text, you need to remember to paste any amended sections into the other document. This make it very difficult to create customised variations of documents, such as cut down versions for managers or new staff, branch-specific versions etc. It becomes unmanageable.

One of the benefits of using some of the alternatives to Word is you can embed a piece of information into multiple documents. In a similar way to how you can use the same image in lots of different web pages, you can use the same chunk of text in lots of different documents. The advantage of this approach is that in the future you’ll only need to change the source, embedded chunk of text when it’s time to make a revision. That piece of text gets updated automatically (or semi-automatically) in all the documents that use it.

Reputation Management – Can user documentation help quash rumours?

Photo of a tiger in the streetIn the ‘Whispers’ episode of BBC Radio Four’s Digital Human programme, Aleks Krotoski explores how rumours spread both online and in the physical world.

As an example, she looked at how two people were able to spread a rumour that a tiger was running loose in London during the 2011 riots.

Aleks claims we are now in a world of misinformation. For organisations, this means they now have to pay attention to any misinformation or rumours about their products and services, an activity that is often called ‘reputation management’.

Seven minutes into the radio show, Nicholas DiFonzo of the Rochester Institute of Technology states groups believe rumours typically because there is a lack of information from official channels, they don’t trust official channels, or because their friends believe it. People use rumours to figure things out.

This means if there is a gap in information, then rumours may fill that gap. For this reason, it’s important organisations publish their Help files or equivalent on the web, so that there isn’t any uncertainty over what your product can and cannot do. If you don’t, whatever Google serves as an alternative source of information will fill in the gap.

Where people might not trust the official marketing content, they are more likely to trust the technical, instructional information. It’s seen as more ‘truthy’.

What do you think?

Please share your thoughts, using the comments box below.

Is there gender bias in your Technical Author job advert?

Simon Morisawa-Bostock pointed me towards an article on gender bias in job advertisements (You Don’t Know It, But Women See Gender Bias in Your Job Postings):

A scientific study of 4,000 job descriptions revealed that a lack of gender-inclusive wording caused significant implications for recruiting professionals tasked to recruit women to hard-to-fill positions underrepresented by women.

Researchers studied gender wording in job advertisements and job descriptions and the effect of gender wording on job seekers. The researchers first established that women’s style of communication is more communal, using more emotional and social words than men’s style of speech.

The researchers linguistically coded job descriptions found in a U.S. Department of Labor database that were predominately populated for masculine-themed words such as active, ambitious, analytical, competitive, dominate, challenging, confident, decisive, determined, independent, leader, objective, etc., as well as feminine-themed words such as committed, connected, cooperative, dependable, interpersonal, loyal, responsible, supportive, trust, etc. The results confirmed that job descriptions for male-dominated jobs contained more masculine-themed words associated with male stereotypes than job descriptions from female-dominated jobs and vice versa.

Alarm bells ring in my mind when people talk about “a women’s style of communication”. As a number of commentators at the end of the article pointed out, many of the words and phrases the researchers identified as “gender-themed” could also be attributed to differing personality and behavioural styles.

Technical Authoring is a profession that has a roughly 50:50 gender split, requiring some so-called masculine traits (e.g. independent, analytical, active) and some so-called feminine traits (e.g. committed, connected, cooperative, dependable, responsible, supportive). However, there are some “masculine” traits you wouldn’t normally associate with the role and expect to see in a job advert - such as competitive, dominate, challenging, confident, decisive and determined.

We do receive, on occasions, job descriptions that don’t really reflect the attributes associated with successful technical communicators. Part of the value a specialist technical author recruitment agency provides is to reword job descriptions so that will attract the right type of candidates. I took a brief look at some of the recent job descriptions we’ve received from clients, and I couldn’t find any evidence of a dominance of “masculine” or “feminine” words in the job descriptions. From that perspective, there was no particular bias that needed to be mitigated.

I  looked at whether some of the “masculine” words appeared in job adverts for Technical Authors posted elsewhere on the Web. Again, there seemed to be no particular bias. Having said that, there were a few notable examples:

“As Technical/Training Author you must boast a great knowledge and experience in technical authoring, a demonstrable record of producing high-quality technical documentation and materials within a software product environment, and experience of training external clients and internal teams. … This role demands a confident, client facing Technical Author who is at with working in a software house.”

“As an exceptional Technical Author you will be adept at delivering reader-friendly, technically accurate and complete product documentation on time to demanding schedules…Our client is looking for only the most exceptional and talented candidates – true rockstars of their profession.”

I suspect these organisations will struggle to find suitable candidates.

What do you think? Have you seen inappropriately worded job descriptions for Technical Authors? Share your thoughts below.

Creating a map showing the location of Technical Authors

Sarah Maddox’s post on how she has added “techcomm titbits” onto an interactive map, prompted me to look at whether we could create a map showing the location of Technical Authors around the UK. It’s something we’ve wanted to do for years, and Sarah’s post suggested it was much easier to do these days, thanks to Google’s applications.

The map needs data, so if you are a Technical Author, please add your details to the map:

We will not include your name or email address on the map. However we do need your name and email address in order to check the integrity of the data and to update you of any developments. You can use the postcode of a neighbouring street, if you wish.

We currently have an intermittent problem with our website. If you see an Error Establishing Database connection message, please refresh the page and it should appear.

RoboHelp 11 review (finally)

robohelp logoAdobe released its latest version of RoboHelp Version 11 (and Technical Communications Suite 5), a while back and asked if we could write a review. There have been a number of excellent reviews, so we’ve been wondering what extra we can say. We’ve decided to address some of the questions we’re often asked by organisations when they’re deciding which Help Authoring Tool to choose.

Continue reading

Contract Technical Author needed for June projects…possibly

May and June are shaping up to be very busy times at Cherryleaf, and we may be looking for additional people to work with us on some of our software end user documentation projects.

If you are a London-based Technical Author interested in a few weeks work in May and June, do contact us.

The big questions in technical communication

David Farbey wrote a semi-existentialist post on the challenges for technical communicators yesterday. I’d like to look at the issue in a different way, by looking at the big questions in technical communication today. The answers to these questions (which may be decided by people outside of the profession) are likely to affect the future direction for technical communicators.

Continue reading