Not so cool tools for Technical Authors – speech recognition software

Our method for creating online courses involves making an audio recording of the presenter, transcribing it, editing the script and then recording the final, video presentation. We’ve tried using speech recognition software to create the transcribed script, and it has been a deeply frustrating experience.

While speech recognition is proving successful for searching and issuing commands (using Siri, Google Voice and Amazon Echo), we’re not sure it will replace the keyboard as the way we create written content.

Continue reading

Cool tools for Technical Authors – travel equipment

We’re sharing some of the tools we use at Cherryleaf. This time we’ll look at travel equipment.

The role of consulting technical communicator can involve travel to exotic places, such as San Diego, Cologne and Swindon. Your travelling experience can be affected by what equipment you have on your travels, so it make sense to take the right stuff with you. You don’t need to wander around places like Frankfurt Airport too many times, with a heavy bag across your shoulder, realise travelling for work can be both tiring and painful.

Continue reading

Cool tools for Technical Authors – video equipment

We’re sharing some of the tools we use at Cherryleaf. This time we’ll look at video recording.

screencast screenVideo is becoming an important medium in technical communication. In addition to screencast videos (walkthroughs of application screens), software like Camtasia and Captivate enable you to include video of people in your presentations. Doing this creates a more TV-like presentation and a more professional feel to your output.

Continue reading

Cool tools for Technical Authors – audio recording

We’re sharing some of the tools we use at Cherryleaf, and this time we’ll look at audio recording tools.

It can be very useful for a Technical Author to be able to record what someone is saying. If you are gathering information from a Subject Matter Expert, you can let them just speak naturally and quickly. This can reduce the demands on their time, and it often leads to a more relaxed conversation. There can be other instances where it’s not practical to use a notepad or computer to write or type notes.

Continue reading

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.

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.

Book review: Every Page is Page One

Every Page is Page One book coverThere’s a joke in education along the lines that students are taught the notes their teachers wrote down at university 20 years earlier…without going through the heads of either.

I mention this because there have been a number of technical communicators who have started to question the technical writing best practices that have been taught to student Technical Authors for the past 30+ years. At Cherryleaf, we show on our advanced technical writing techniques course how some of the largest websites have been breaking the generally accepted rules for writing User Assistance – companies that test and test again to see what works best for their users. Ray Gallon of CultureCom has been developing his cognitive approach to User Assistance, and Mark Baker has been developing and promoting the idea of “Every Page is Page One” (EPPO) Help topics.

Mark has published his ideas in a new book called “Every Page is Page One“. I was asked to review an early draft of the book, and, over Christmas, I was sent a copy of the published version.

In a nutshell, Mark’s argument is that, with Web-based content, you don’t know the context in which people are reading a Help page. You cannot assume that they have read any other pages prior to reading this topic. Therefore, you need to treat every page as Page One, the starting point, and include more introductory, contextual information in your topics. He argues that most Technical Authors have misunderstood minimalism, and the EPPO approach is actually more consistent with how John Carroll (the creator of minimalism) recommended User Assistance should be written.

The book provides recommendations on the level of detail you should include on a page before you need to create a new topic, and when and where to create links to other pages. He also compares EPPO to Information Mapping and DITA, and outlines how EPPO can complement these standards.

Reading the early PDF draft with a reviewer’s eye was struggle at times, but reading the final version in printed book format was an easy and enjoyable exercise. Perhaps reading some sections for a second time helped, as well.

We agree with a great deal of Mark’s ideas. We agree with the general idea of self-contained topics that provide the context for a task. We agree with the need for mini-Tables of Contents and a bottom-up approach to writing. We agree that tasks should include some contextual information. We agree online content can be atomised too much. We also liked his analysis of why screencasts are so popular, and the secrets to their success.

We have a few minor issues. Mark cautions against duplicating content on more than one Web page, because it’s bad for Search Engine Optimisation. We believe you should write efficiently in a way that’s best for the user, and that it’s up to the Search Engines to improve their algorithms so they can differentiate between “good” duplication and “bad” duplication. Google should be adapting and learning from the way good content is written, not us having to create sub-optimal content in order to satisfy Google.

It’s a book for people involved today in writing online User Assistance. Although the book is very clear and well structured, you probably need to have some experience of creating User Assistance to fully understand everything that’s covered in the book. It’s an important contribution to the discussion over whether technical communicators have focused too much on production efficiencies to the detriment of creating content that’s actually of value to their users. It’s worth getting a copy of this book.

What would a Technical Author ask from Santa?

Santa Claus - WikipediaSaint Nicholas’s day has passed, which means Christmas is getting close. So what would a Technical Author ask from Santa Claus?

One thing we could request is the ability to embed one Google document inside another. That would mean that Google Docs could support some basic content reuse.

Another would be to request Madcap Flare’s DITA support to be extended, so that you could create edit native DITA files.

We could ask him to provide a standard technology format for providing Help for mobile applications.

We could also ask him for a way to use Siri and Google Voice Search to interact with our user guides.

So what would you ask Santa to bring? Please share your thoughts and ideas below.