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.

Update on our iPad as a documentation device training course

Here’s an update on the training workshop we’re currently developing on how to use the iPad and other tablets as a device for delivering documentation. The trainer’s slide deck has been completed and is out for review. Once that’s been signed off, we’ll check the timings and determine if this is a half or full day session.

We’ve selected the venue in central London, so, after that we’ll be able to announce the date and prices for the course.

The primary focus will be on the iPad, but we can also cover what’s possible on other tablets.

iPad

We’ll cover items such as:

  • How organisations are creating, in just 30 seconds, online magazines for “getting started” guides, tips and tricks, training guides and FAQs, using existing content from your Web site and blogs.
  • Apps for reading content
  • Tools for creating content
  • What works/ what doesn’t work
  • Implications for the future, how to use the iPad to gain and edge over your competition etc

Let us know if you would be interested in attending this event.

Technical writing in the Cloud

One of the most popular developments in computing in recent years has been the emergence of cloud-based computing and Software as a Service (SaaS). Examples of cloud-based computing include Google’s GMail: Instead of an application being installed locally on a user’s computer, it runs on a remote server, accessed via the user’s Web browser.

So is technical writing likely to move to the Cloud? Let’s look at the different approaches.

Why would you want to write using a cloud-based application?

There are a number of reasons why a Technical Author might want to use a cloud-based application. The first reason is cost. Instead of purchasing an application, cloud-based applications are typically offered on a monthly fee basis. If you’re looking to move to a DITA authoring environment, this spreading of costs could prove an attractive alternative to the upfront costs associated with buying a DITA solution.

There are other reasons, why you might also consider moving to a cloud-based solution:

  • If you have staff, a technical writing partner (such as Cherryleaf) or contractors working remotely, cloud computing means you can quickly and easily add them into your authoring environment.
  • If you want to work in a collaborative authoring environment, cloud-based applications typically enable you to do that.
  • If you use a third party company (such as Cherryleaf), you have the opportunity, at a later date, to log into the system and make any minor updates (following updated releases of your product) yourself.

Check in/out

You don’t necessarily need to move to a cloud-based environment, if you want to have remote workers and/or collaborative authoring. The most popular authoring tools, such as RoboHelp, FrameMaker and Flare, use a check in/out model instead of a cloud-based approach. Writers can “check out” a topic from a project and work on it remotely. They can then “check in” the completed topic back into the project, via email or SharePoint.

Your authors will all need to have the Help Authoring Tool on their computers, and you cannot watch them as they write, but it’s worth considering.

SaaS

If you’re looking for a SaaS authoring tool, then there are a number to consider:

  • DITA-based authoring applications and services, such as Doczone, DITAweb and Stilo Migrate
  • Help Authoring Tools, such as HelpConsole and Author-it Live
  • Wiki-based technical authoring applications, such as Mindtouch Cloud and Atlassian OnDemand
  • Word processors, such as Google Docs

You’re usually unable to add any additional plugins, which you’d be able to do if the software was installed on your computers or servers.

You may also need to consider where your data is actually being stored. Data privacy rules differ in the USA and the European Union –  the USA’s Patriot Act, for example.

Your own private cloud (VPN)

Some organisations simply add remote workers to their existing network. The organisation has its own private cloud, a Virtual Private Network (VPN). Typically, it’s up to the IT department as to whether a remote user will be given access to a system. You may need to acquire licences, and you may need to wait for IT to set this all up for you.

An alternative approach is to create a private cloud for your own department. You can create a server in the Cloud, using Amazon’s EC2 service, or using alternatives from companies such as RackSpace or Microsoft (Azure). On this server, you could install for example, a customised version of the Authoring application (containing all the plugins and macros you require), and provide remote workers with a web address, user name and password for them to log in. With VPN server prices starting at $20/month, it’s an affordable option.

If you decide to do this “under the radar” (i.e. don’t tell the IT department you’re setting up your own VPN), you need to make sure you’re conforming to your organisation’s IT security policy. Otherwise, you could be in trouble.

Are you writing in the Cloud?

The reasons for using cloud-based applications seem to be as valid in the Technical Publications department as in other departments. So it’s likely we’ll see a growth in the uptake of this type of service.

  • Are you writing in the Cloud? How have you tackled this problem?
  • Is writing in the Cloud a good idea?

We welcome your comments.