Your policy and procedures manual as software

Jared Spool tweeted this morning:

HyperCard was a hypertext program that came with Apple Macintosh in the 1980s. It allowed you to create “stacks” of online cards, which organsiations used to create some of the first online guides. It also contained a scripting language called HyperTalk that a non-programmer could easily learn. This meant HyperCard could do more than just display content: it could be used to create books, games (such as Myst), develop oil-spill models, and even dial the telephone.

Continue reading

SharePoint for documentation projects

Most of the Technical Authors I have met don’t have a good thing to say about Microsoft SharePoint. In many ways, it represents how not to publish content online. It is seen as encouraging people to move print-optimised documents (Blobs) around, rather than units of content (Chunks), and users are typically left to rely on search to find which document contains the information they are looking for.

For all those issues, SharePoint may still have its place – for managing documentation projects.

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.

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?