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

Where do the new trends and ideas in technical communication come from?

 

Sometimes we hear Technical Authors complain that the Help Authoring Tool vendors are not innovative enough. We believe that’s an unfair criticism, and that it’s unrealistic to expect the vendors to lead changes in technical communication. The new trends and ideas in technical communication need to come from other places.

We have moved away from Microsoft defining the universally accepted standard for online Help and the Help Authoring Tool vendors working within this framework. With no dominant leader defining the future for User Assistance, making small incremental changes is a less riskier option for the vendors. It’s safer to implement an idea that been proven to work and has been accepted by the technical communications community, than trying to make a major change and hope everyone will adopt it.

So where else will we see new trends and ideas emerging? Does technical communication innovation happen in the same was as it does in science (often in waves of rapid revolution)? Is it like the fashion industry (where ideas from a few leaders in couture work their way down to everyday clothing)? Or is there some secret body that’s making the decisions in the shadows for everyone?

Continue reading

Searching for key words and phrases in training videos – Adventures in media synchronization

One of the limitations of video-based information has been the difficulties for users in finding a particular piece of information in a video. Usually, they have to watch the whole video, or “peck and hunt” to get to the moment containing the information they were searching for.

As we’ve mentioned in previous posts, HTML5, an emerging Web standard, enables Technical Authors and courseware developers to synchronize different media. One application of this is enabling users to search a text for a key word and then start a video or audio at that point. Here is an example.

Searching for key word or phrase in a video - example

In addition to making it easier for users to search videos for the information they need, it will also mean the pages will be more likely to appear in the search engine rankings. In other words, there will be an SEO benefit as well.

Synchronizing text and video within Web pages will become a lot easier in November 2012, when we are likely to see the the introduction of authoring tools containing this functionality (at the moment you need to be familiar with HTML and JavaScript).

We believe this is an exciting development in the field of user assistance.

Writing clear policy documents

Clear policies and procedures can have a profound effect on any organisation; they ensure that people know what they are doing, systems work properly and the people within the organisation are confident that the information in the policies and procedures is accessible, easy to understand and current.

However, writing clear policy documents can be very difficult to do.

Before you can write a good policy, you need clear decisions on which to base your writing. If the organisation doesn’t have a clear sense of what it wants to do, you as the writer will be compromised – there is only so much you can do with confusing or incomplete information. Policymakers must agree on policy before you, the writer, can write the policies.

You must also decide on your audience – whom you are writing for. The answer is often, our policy is for everyone, they all need to read and understand it. However, this means you have to write a document that must address multiple audiences with different agendas.

The temptation is to write policy documents primarily for those who audit the policies, which means the documents are often written in the passive voice. The problem with that is it can cause  a reader to become a passive spectator – they don’t ‘get’ what they are expected to do. The rules here is simple:

  • Imagine the least experienced user and write for that person.
  • Write primarily for those who need to use or implement the information.

Policies and procedures should always accomplish something – never write a policy or procedure just because it seems like a good idea. Very often policies and procedures can be knee jerk reactions to an incident. Somebody makes a mistake and someone else says “we should put a policy in place in case it happens again”.

You need to be a ruthless editor to avoid repetition and confusion across a myriad of documents. Break information down into ‘chunks’ or ‘topics’, with each topic containing one subject with a specific purpose, and then refer to (or embed) that topic in the other documents.

We’ve been working on a project to simplify policy documents within an NHS Trust. It’s a challenge simplifying a set of complex interlocking documents, but the results can be striking – helping staff understand why they should do things in a certain way and what the organisation is aiming to achieve.

Tackling the challenge of writing sales proposals and RFQs

Standards and processes permeate nearly every area of business today. They enable management to control, direct and delegate, giving people the ability to focus attention on the more difficult issues the business faces. Processes drives predictability, consistency and efficiency.

Despite all these benefits, sales departments have been much slower to move down this path. Sales people usually baulk at the idea of processes, complaining that “form-filling gets in the way of actual selling”.

Yet, according to Dario Priolo and Bethany Schultz, from sales training company Miller Heiman,

Our research clearly shows that “Winning Sales Organizations” take a much more scientific approach to selling and sales management than others. While there will always be a certain art to selling, it’s an increasingly sophisticated business world…How much better would a CEO sleep at night if he knew his sales force had a consistent, professional approach to interacting with customers! An improvement in these factors helps drive revenue predictability, reduces cost of sales and increases sales force productivity—all critical business objectives.

Miller Heiman argues that a sales process can help sales people “sell more and sell faster”.

Any successful initiative must include tools to streamline the process and remove any barriers to change. In this context, it makes sense to streamline one of the most time consuming aspects of selling – responding to Request for Quotation and other forms of sales proposals.

As we mentioned in our post “Building intelligence into business documents“, it’s now possible to create a system that can build the bulk of the document in a matter of minutes, leaving the writer with the task of customising the information to suit the requirements of each particular situation. These systems can even include training videos and text to guide a writer through the process of developing a new document, as well as enforce consistency and standards.

In the near future, we’ll be providing details on some the solutions available to organisations that want to improve the process of writing sales proposals and RFQs.

Please welcome guest blogger Malcolm Tullett

We welcome our latest guest blogger, Malcolm Tullett. He runs a fire, safety and environmental consultancy and training company called Risk and Safety Plus, and is the creator of PROPA.

Malcolm’s mission is to spread the word that risk and good business are not mutually exclusive – they are simply two sides of the same coin. He’ll be blogging about business processes and communicating change within an organisation.

Malcolm Tullett

PROPA is a concept that won an Institute of Engineering Technology (IET) award for innovation. It has now been developed into a online intelligent operations manual that drives efficiency and effectiveness whilst seamlessly addressing compliance. PROPA presents end-to-end process mapping that enables you to analyse risk areas before an event and has the capability to actively change a process to mitigate risk and deliver quality data for business operations. Contact us for more details.

Welcome Malcolm!

Your online grammar reference guide

We’ve added a link on our Web site that will take you to the online grammar reference guide offered by Grammar to Go.

Built for business, Grammar to Go is your personal grammar specialist, ready to answer your questions wherever and whenever they arise.

It is very popular with professionals who spend their valuable time correcting errors in English before they can review reports and other documents.

How much time do you imagine is wasted on this? 

17 days to better grammar

You can sign up for a free piece of expert advice in writing skills every day for 17 days. It’s a great way to check your knowledge of correct English.