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.

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

Changing times in technical communication 2 – Workflow

Science Museum/Science & Society Picture LibraryWe’ve been on the road in recent days and weeks, visiting different documentation teams, and we’ve found there are distinct signs of change. In this post, I’ll look at how we’re starting to see the workflow for creating User Assistance beginning to change.

We found many documentation teams overstretched and starting to be asked how they could create content for new products that were coming along. Some organisations have decided they can only deal with this extra workload if they rethink the workflow for how content is created.

Continue reading

What’s the best way to deliver distance learning for technical communicators?

You’ll find our latest post for the Society for Technical Communication on its Notebook blog. It’s called What’s the Best Way to Deliver Distance Learning for Technical Communicators?

One of the most frequent questions we’re asked at Cherryleaf is if we can deliver our advanced technical writing techniques course as a distance learning class. We only offer it as a classroom course, which effectively limits us to teaching students who are based in the United Kingdom, Ireland, or mainland Europe. Being able to offer a training course worldwide is tempting, but is it really possible to deliver distance learning when you want to get people to question and rethink the way they do things today?

See: What’s the Best Way to Deliver Distance Learning for Technical Communicators?

Webinar: The changing nature of content

You’re welcome to join us on our upcoming free webinar, “The changing nature of content”, which will be held at 7pm (GMT+1) on 24th April 2013.

In recent years, technical communicators have focused on improving User Assistance through new technologies and systems, with the assumption that the nature of the content the tone of voice, the writing style ­ should remain the same. In this free webinar, sponsored and hosted by Adobe, we’ll investigate whether the tried ­and tested writing methods from past decades still make sense today. We’ll look at the reasons why some organisations are “breaking the rules” with the User Assistance they provide.

The registration details will be posted to the Adobe online events Web page in the next few days.

The DITA XML authoring barrier for non-Technical Authors

One of the challenges for organisations moving to a new content management system for their user documentation is selecting an authoring tool that is:

  • powerful enough, and
  • can be used by non-Technical Authors as well as the professional Technical Authors.

Many organisations want staff, such as developers, to be able to add content to the system directly – without having to pass it over to the Technical Publications department. The difficulty lies in that many tools for authoring in DITA and other XML schemas are daunting to those unfamiliar with the underlying principles of DITA and structured content. It’s even more challenging if you’re someone who is only going to write content occasionally.

One approach is to create templates, with defined fields that need to be filled in. Another is to get staff to write in Word, again in conjunction with a template, import the text into the content management system and then map metadata and other semantic information to the content at that stage.

Is it an unsurmountable problem? Should we just accept that writing semi-structured XHTML content (such as wiki-based content or WordPress-like authoring environments) is a better compromise? What you lose in modularity, you gain in having an easy-to-use authoring environment. Alternatively, do we need to recognize we’ll always need specialists who can convert text into the appropriate format - the equivalent of the typing pool or typesetters?

It has bearing on the role and value of Technical Authors. Is it their main value in writing skills, information management skills, editing skills or in using a specialist tool? If the organisation believes “everyone can write well”, then is their value in using software that’s complex and tricky to use?

How the new Kindles might affect the role of the Technical Author

Here are some initial thoughts on how the new Kindles from Amazon might affect the role of the Technical Author.

Yet more diversity in reading platforms

Technical Authors know this already – their content needs to work on lots of platforms and across different mediums. It’s more evidence that the layout must not be baked into the content; if the two are controlled separately (by using cascading style sheets to modify and adapt the layout), then we can publish to lots of different devices. Technical Authors do this today, but it’s still worth mentioning.

The distinction between video and text based information is likely to become blurred

The Kindle’s new Whispersync for Voice feature means that users can switch between reading and listening. If this extends into the narration of video, in the future, we could see users toggling between text-based content and video tutorials. With the text and the narration synchronised, the video could start from the last word the user was reading. Mozilla’s Popcorn maker project could make this possible across all tablets, not just the Kindle.

Video may be come less serial and more hypertext-like

Amazon’s X-Ray for movies enables users to navigate and explore a video by characters:

Simply tap on any scene to instantly see which actors are currently on screen, jump straight to other movies in which they star, and more.

Wouldn’t it be great if this could be applied to video-based tutorials? For example, you might stop a clip on installing a product to see which tools you need, and then navigate to the other times when you might also need to use that tool.

The time spent reading may increase

Each year, the ability to have hundreds of books on your person, ready to be read at any time, increases. What’s more, with the passive screen technology, people can read “online” material for longer.

Reading will become a more collaborative experience

The Kindle encourages users to share passages and notes on a book. In the future, it may become the norm for you to read a user manual and share your experience with other readers of the same guide.

What do you think?

Announcing our ‘Using the iPad as a documentation device’ workshop: 31 May 2012

We’ve completed the slides and booked the training room for our new workshop, Using the iPad (and other tablets) as a documentation device:

With more and more people using the iPad and other tablets for reading technical documentation, this workshop looks at how tablets can be used by organisations to design and deliver technical documents and other forms of User Assistance.

The course will be held in Central London on Thursday 31 May 2012, 9.30am-12.30pm.

You do not need to have a tablet to attend this course, or have previous knowledge of using a tablet.

This course is aimed at Technical Authors and others developing technical documentation and other forms of Help for users.

Places cost £175 ex VAT. For more information, and to book, see Using the iPad (and other tablets) as a documentation device.