Do you need a Documentation Manager when Technical Authors are embedded into Agile project teams?

Earlier this week, I was asked my opinion on whether a Documentation Manager was needed when the individual Technical Authors are embedded into Agile project teams.

My response was that a Documentation Manager mainly provides people management, project management, process management and content management. If a Technical Author is a member of a software project team, then that team’s Project Manager is probably providing the people management and the project management to the writer.

That leaves the need for someone to manage the processes and manage the content. I suggested managing the content could be done by someone with the role of Editor (or “Content Wrangler”). They might also look after the processes, or they could have another writer take on that responsibility.

It’s then a decision as to whether the organisation sees these roles as senior to the technical writing positions, or as a specialism and consequently on the same job grade.

It does leave the management of the writers’ career progression falling through the cracks, unfortunately.

How do others deal with this issue?

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.


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.

Our 2nd ‘Trends in Technical Documentation’ Talk – 9th May 2012

Cherryleaf is curating and hosting a programme of talks on trends in technical documentation. At these sessions, there’ll be presentations from respected members of the Technical Communication profession, plus the opportunity to network with your peers.

The next talk is:

User Assistance in a Social World

We’ll be looking questions, such as: Where does technical documentation fit in a world of Twitter and social media? Is User Assistance different in Social Media applications?

The speakers will be Briana Wherry, Director, Programme Management of Alfresco Software and Dr. Adrian Bredenkamp, CEO of Acrolinx GmbH.

Date and time: 9th May 2012 10.01pm-12.31pm
Location: Birdcage Walk, London SW1H

The event will be free, but with priority for places given to our customers.

Spaces are limited to 14 delegates

Contact us if you’d like to attend.

This event will not be recorded or streamed.

Will the growth of tablet and mobile phone based reading lead to the return of Clippy?

Microsoft Clippy (aka “Office Assistant” or “Clipit”) is a feature remembered by many users of Microsoft Word. It assisted users by way of an interactive animated character, which interfaced with Office’s online Help. Although the concept of “embedded” or “persistent” Help was good, its application in the real-life working environment was not well received.

With more and more people reading information via tablets and mobile phones, and with the new technologies they contain, perhaps it’s time to revisit the concept of Clippy. Perhaps it can be done right this time?

There are two technologies that tablets and mobile phones contain which are worth considering. One is haptic feedback, the other is ambient technology.

  • Haptic feedback is technology that interfaces with the user through the sense of touch – typically through your device vibrating.
  • Ambient technology refers to electronic environments that are sensitive and responsive to the presence of people.

An example from the e-learning environment is Evernote Peek, which makes use of the iPad’s Smart Cover to present information.

Perhaps instead of an animated character clamouring for our attention, a more subtle notification by a vibration or a glowing button might be a better way to tell users help is available that can guide them through their task.

We’re not aware of any User Assistance that is using haptic or ambient technologies today, so do let us know if you’ve seen any examples out there.

Creating franchise operations manuals that are customisable and controlled

Creating an operations manual is a key part of franchising any business, as it helps ensure each franchisee is operating in the way that made the original, franchised, business successful in the first place. You want reliable, repeatable, consistent performance from every franchised location.

However, it’s often the case that there needs to be slight variations between each franchised location. The challenge is, how can this be reflected in the operations manual?

For example, let’s say a company called Doner-Summa decides to franchise its business selling turkish doner pizzas and have franchises in Leeds (in the UK) and Dublin (in Ireland). It wants to have standard operating procedures in the case of a fire, but it has the challenge that the layout of each store is different, as is the emergency telephone number between the two countries.

The solution is to create a franchise operations manuals where certain sections are controlled centrally by the franchisor, and where other sections can be customised to reflect the particular situation of each franchisee:

When the Leeds branch adds its content to its operations manual, it contains important and specific information relevant to their situation. In this case, the location of the fire alarms and the evacuation point:

The Dublin branch operations guide looks similar, but the building diagram and the emergency number are different:

With this approach, Doner-Summa has not passed over all control of the manual to the franchisees. It still has the ability to make iterative improvements to the processes and procedures from the centre.

Let’s say, for example, Doner-Summa discovers the procedure states people should contact the operator, when they should contact the fire brigade. It can make a change to the centrally controlled core procedure, and this change will auto-magically be inserted into all the franchisees’ versions of the guide.

Change made to the core procedure here:

Results in the franchisees operations manuals being automatically updated to reflect the change:

Of course, any printed versions of the operations guide will only be updated when a new version of the guide is printed out by the franchisee. However, it’s possible for an automatic notification email to be sent out to every franchisee whenever the core content has been amended. Also, any online or  tablet versions of the manual will have been updated in real time.

Note: Turkish pizzas do exist in Germany. They are donor kebabs wrapped in a burrito-type bread instead of pitta bread. Doner-Summa is not meant to reflect any existing business with the same or similar name.

Testing the Scaffolding (drop down list) plug-in for Confluence 4

One of the attractions of using Confluence to create reports is the ability to enter some of the content quickly by selecting items from drop down lists. This technique has been the key ways that one of our clients has been able to reduce the time they need to write reports from 1.5 days to 2.5 hours.

Although version 4 of Confluence has been out for a few months now, it’s only in the last couple of weeks that the plug-in for creating these drop down lists has been updated to be compatible with the new version.

So, does it work?

We’ve found the drop down lists worked in version 4 when we created new pages from scratch. However, the drop down lists didn’t work on reports originally created in Version 3 of Confluence. We did find out what was causing the problem, and the fix is to re-enter the drop down options in your lists. If you’re migrating content from version 3 to version 4, you’ll need to bear this in mind.

The drop down lists work well in Firefox and Chrome, but they looked slightly odd in Internet Explorer.

To use the drop down lists, you now click on a new button called “Edit Content” that’s at the top of the page – a more intuitive way than before.

Do cave paintings reveal the origins of the Health and Safety user manual?

Recent investigations into the famous Lascaux cave paintings in France suggest the images might actually be the first ever Health and Safety manual. This discovery could mean the professions of both Technical Author and Health and Safety Officer began significantly earlier than is commonly believed.

A paper released today by Professor Miriam Webster of the Université de Riz Lacroix proposes the paintings actually describe the safe hunting and handling procedures for livestock. Professor Webster said in an interview for Le Figaro:

When I saw the outline of a hand on the cave wall, it suddenly struck me how similar it was to the hand symbol we see around us on safety signs today.

Safety sign from cave painting Flickr image: BotheredByBees
Modern day hand safety sign

Although hi viz jackets and safety goggles were obviously not around in those days, you can make out some primitive safety equipment in some of the hunting scenes.

Hunting scene containing perhaps a primitive form of safety barrier? Flickr image: Chico Ferreira

Whether the creators used any form of primitive help authoring tool seems unlikely, but it will surely give a boost to the technical communication profession to know they are perhaps one of the oldest professions in the world.