"I'm a technical writer" slideshow challenge

Using the photos in the "I'm a tech writer" project, can you make a better slide show for promoting technical writers than this? Contact us and show us what you've created.

Technical Writer - Exploding the myths

View SlideShare presentation or Upload your own. (tags: writing writer)

Would you like to take part in our benchmarking survey of UK Publications teams?

Cherryleaf is undertaking a benchmarking survey of Technical Publications teams based in the UK. Participants will be give a copy of the summary report of our findings that we'll be putting together.

If you head up a team of 3+ writers, which is based in the UK, and you'd like to participate, then please contact us.

In a downturn, is it better to use contractors, permanent staff or an outsourcing company?

In a downturn, priorities in a business often change, and these changes can affect technical authors as much as others. At the London Connections event earlier this week, where I was promoting Cherryleaf's technical writing services, I was chatting to Mike Southon about business strategies in a downturn. Mike is Visiting Fellow in Innovation and Entrepreneurship at London South Bank University, amongst other things, so I value his judgement. He said, in a downturn, businesses should focus on its Return on Investment, minimising risk and watching its cashflow.

So, does this mean you should favour contract technical authors over permanent staff, or vice versa? Should you outsource technical writing work instead? Actually, each option has its merits.

The case for and against contractors

Contractors offer flexibility to a business. You can increase and decrease the amount of people more quickly than you can by taking on permanent staff.

This ability to reduce costs quickly is one of the main reason why organisations often begin reducing costs by getting rid of contractors. Contractors can appear expensive compared to paying for permanent staff. This means there's a temptation to avoid using contractors at all during a downturn. There is often a premium, because you're using paying for someone who is good and who is experienced. However, remember the contractor is bearing holiday sickness and taxation costs that otherwise would be borne by the organisation.

It's worth bearing in mind that in terms of uncertainly, this flexibility could be a good reason to favour contractors over permanent staff.

The case for and against permanent staff

Permanent staff offers continuity of service. They can also be part of a team that works in a consistent manner that conforms to the organisation's long term goals. They may be able to be deployed elsewhere, such as in usability testing, training or support.

However, it is less easy to reduce the number of permanent staff than it is to reduce the number of contractors. The process can take much longer and can be more stressful.

The case for and against outsourcing

Outsourcing can mean using a technical writing company, such as Cherryleaf, to write an online Help file (or other forms of user assistance) for a specific project. It can also mean establishing a more longer term relationship - acting as the technical publications department, being available on a "call off" basis or acting a part-time (say three days per week) resource.

Outsourcing offers benefits similar to contractors, with the added benefits of continuity of resource, project management, predefined deliverables, and the collective knowledge and of expertise that organisations can offer over an individual. It's worth considering when work is unevenly spread throughout the year, when it comes in peaks and troughs, or if there isn't enough work to require a full time resource.

Outsourcing does not work well when deliverables cannot be defined, and the information needed to do the work is not available (although this is true of all projects). It's often done off-site (but not off-shore), as the work can be scheduled around other writing projects and a team of writers can work together, but some organisations are able to work with such an arrangement.

What about offshoring?

Offshoring of technical writing is something that is less common than the offshoring of programming resource. The standard pros and cons of offshoring apply (lower initial costs v quality and project management issues), but there are some additional considerations. The key skills needed in a technical author are great writing skills and good project management skills. This means nearly always that the person needs to be a native English speaker. A non-native English speaker can write a sentence that is grammatically correct, but be written in such a way or use a word that just would never be used in the UK or other English speaking countries.

The "do nothing" option

Some organisations opt not to develop any user assistance at all. This saves them the cost of developing online Help, user manuals and other forms or assistance. Is this a false economy or a sensible saving?

User Assistance is often seen as a necessary evil, and its value can be hard to measure, in the same way that quality can be hard to measure. It depends if you are producing the equivalent of an Austin Allegro (UK's "Ford Pinto") or a Toyota Corolla. User Assistance is tied up with an organisation's long term view of its customers. The more important it sees customer loyalty and after-sales service, the greater the value of user documentation. User Assistance, be it delivered via Web pages, paper manuals or online Help provides immediate assistance and can reduce the number of calls to support lines and the number of dissatisfied customers.

There's a poem I once saw on the Web that began something like, "If an application doesn't need user assistance then is there really a need for the application itself?" It's like the idea of the software that sells itself - in a perfect world, you wouldn't need a sales team either.

Could the programmers write the documentation?

Programmers do write user documentation, and often it shows. If the programmers have nothing better to do, then there could be a case for them writing the documentation. However, programmers are not always a cheap and available resource.

They often suffer from the "curse of knowledge" - they know so much about the system that they cannot see the world as a user (beginner or advanced) does. It's unusual for a programmer to be also a good technical author. Indeed, perhaps there is a stronger case for the users to write the user documentation instead?

Conclusion

All these options have different merits, which is why organisations such as Cherryleaf needs to offers a range of options (outsourcing staff, contract staff and the placement of permanent staff). Your organisation is unique and the requirements you have will differ from others. The key factor is often the spread of the workload. If work comes in peaks and troughs then outsourcing may be the best option. If the nature of the work itself is unclear then permanent staff may give you more flexibility.

The challenge for us at Cherryleaf's is to use our expertise in the field of documentation to help you save money: by finding the best solution for your business needs and giving you a good return on your investment.

What do you think?

You can comment below.

Poll: The next 12 months - What will they be like for you?

Get your own Poll!

The rights of the technical reader

At the Roald Dahl museum there is a poster on the wall entitled "The rights of the reader". It's a wonderful ten point manifesto drawn up by Daniel Pennac in his book of the same name.


Unfortunately, the poster appears to be no longer available for download from the Walker books Web site, but it is available elsewhere.

The rights include:

The right to skip
The right to read anywhere
The right not to finish

Would any of the rights differ for a technical reader?
------
(Addendum)

Our thoughts were:

The right to read in a medium that suits me
The right to be listened to
The right to up to date information
The right to expect the information will be understandable
The right to be able to find the information I need

What would be the corresponding rights be for the technical writer?

Our thoughts were:

The right to be given enough time
The right to be given accurate information
The right to have correct tools for the job

User Assistance for the future: simple steps you can take today

We've decided our presentation at the UA Conference Europe 2008 will be on "User Assistance for the future: Simple steps you can take today".

We'll be looking at developments which may (a) fundamentally change the expectations of users towards User Assistance and (b) change what/how technical authors deliver.



We'll be speaking on the first day of the conference, at around 12.30. It's a short presentation, which is great, as this means we have to focus on the core message we wish to convey.

We'll be drawing on developments and ideas outside of the technical communication sector, and how these could affect the work that we do. We'll be looking at some research we've carried out. We'll also be looking at simple steps technical authors can take today. Like most of our presentations these days, it will be a very visual presentation with as few bullet points as possible.

How do Technical Authoring teams work?

This looks like an interesting event:

"The next Cambridge ISTC group meeting will be a discussion about how technical authoring teams work:

* how are teams structured (and do all the technical authors in the
business work as a team)?
* how is work divided between authors?
* how do authors work with other people in the business?
* what is successful about that way of working and what are the
limitations?

We'll hear about the experiences of 5 or 6 people who work (or have worked) in a variety of different contexts (as a contractor joining other authors in a company; as part of a permanent team of authors; as someone for whom authoring is only part of their job).

This will be organised as a relatively informal round-table discussion with lots of time for for Q&A and discussion.

Here are the details:

Date: Tuesday 5th August
Time: 7pm
Venue: Red Gate offices (Jeffreys Building, St Johns Innovation centre, CB4 0WS
More detailed instructions are on www.red-gate.com"

The event is free and open to anyone to attend, but numbers are limited so please let them know in advance if you'd like to come.

How many technical authors know about Mooer's Law?

In 1959, Calvin Mooers, a researcher into the science of Information Retrieval, developed Mooer's Law:

"An information retrieval system will tend not to be used whenever it is more painful and troublesome for a customer to have information than for him not to have it."

Its original meaning meant: people will avoid an information system because it gives them information which is painful and troublesome to possess.

However, Mooer's Law was reinterpreted by Roger Summit and others as meaning: "information will be used in direct proportion to how easy it is to obtain".

According to the latest edition of E&T magazine, a study by the Centre for Behaviour and the Evaluation of Research (CIBER) at UCL for the British Library noticed readers are now "power browsing" (i.e skimming or scanning) online content.

"It almost seems that they go online to avoid reading in the traditional sense".

One of the common practises in technical communication and user assistance is to publish "deep learning" content on paper, rather than online. This research would seem to back this up.

However, the research does note a concern: people may be getting out of the habit of deep reading, as a consequence of reading most of the time from a screen.

If this is true, then this would cause problems not only in the for academic research field, but also in the user assistance/technical communication field too.

Should we worry about this?
What should we do?

What Web 3.0 is really about for technical authors

On Monday I had a good chat with John Fintan Galvin, who is a true expert in Web technologies and SEO, about Web 3.0.

According to Fintan:

"Web 3.0 is all about the automation of connections between resources in a context-sensitive way. These connections can be made between anything defined as a resource, e.g. people, content, systems etc.

For example

Now - You go to Google, you type in a search phrase, you find a few companies and based on your internal model you establish a relationship and you do business.

Web 3.0 - You type in your search query and the system does the rest based on what you have told it previously and what it can learn externally.

If I search for an item that is:

* below £5 in value
* something I have purchased before
* available from the company I made the purchase from last time
* whom I was happy with them
* and they're in the first 3 results
* and I have an account

then place the order.

In simple terms, everything will have much clearer definitions on what they are and what they provide. This allows for the creation of automatic relationships between resources for specific tasks or functions within given contexts. Underlying all of this will be a system of trust that allows for the programmatic decision making…

The primary issue is to get people to understand that it's not just a sound bite, but an actual structural change in the way business will be done and that they have to prepare for it."

How does this relate to technical communication?

Today, online Help (user assistance) is developed in a way where information is provided through manually created links (tables of content and indexes), rather than purely by automated (Google-type search) links. If semantic intelligence can be built into linking and search results, then technical authors should take advantage of this.

In a technical writing context, the example could change.
If I search for an item that:

* is written in British English
* has been optimised to be viewed on a mobile phone
* is available from a site I trust
* is for advanced users

then show me that page.

The concepts are similar to “information types”, a concept Microsoft considered and dropped in the 1990s as part of HTML Help. Information types promised the ability to present different views of the information based on the type of user, content etc. Where it differs, almost ten years on, is the whole concept can be extended much, much further. Web 3.0 promises are more flexible, more automated system with the capability of information being aggregated from a range of disparate, trusted sources.

It would require well-defined rules of engagement with other businesses or data sources. If information is being drawn in from outside your domain, then it needs to be from a trusted source and in a trustworthy form. In such an environment, technical authors would need to do much more statistical analysis of what users want and how they behave – both modelling scenarios and analysing behaviours.

Geek Corner

It could be that the Open-ID standard is extended to include information on how a users prefers to receive user assistance – their level of expertise, preferred learning style etc.

Fintan stated:

”The technologies that count are RDF, OWL, HTTP and SPARQL. I would also add SVG but then again I am obsessed with it. Ensure that you have first class knowledge of relevant ontology / taxonomies related to your industry and general movements towards standards in inter-industry areas.”

Disclosure

Fintan’s company, IO1, and Cherryleaf are both shareholders in a joint venture, ECS Ltd.

Brent Hoberman on the three biggest trends

I was Codrin's leaving party last night (he's emigrating to Switzerland), so I missed Brent Hoberman's presentation at Ecademy's event in London. Brent is well known in the UK as an Internet pioneer, as a founder of Lastminute.com.

Andrew Wilcox, a mind mapping expert, did attend, and his notes from the event show that Brent talked about the three biggest trends businesses should watch out for.

Brent said those trends are likely to be:

1. Location based mobile information
2. New screen technology, promising paper-equivalent resolutions
3. Video IPTV

All these trends could be incorporated into user assistance, such as online Help. So will we see technical authors using these capabilities at some stage in the future?

Failure in technical communication

JK Rowling made a great commencement speech recently at Harvard University - on the topic of failure.



Failure is something that stalks the world of technical authors.

Failure affects our clients. Users often have to feel they have failed before they call up online Help. It is said that Microsoft nearly renamed "Help" in Vista, as a way of encouraging users to call it up more. However, they couldn't find a better word than "Help".

Failure is viewed differently in other cultures. I remember Patrick Hofmann talking in 2006 about how people from Japan read and re-read instructions carefully before they start a task, so that they won't make any mistakes. "Bodge", a typically British word, has no direct translation into the German language.

Should technical authors be comfortable living in a world of failure?

Jo Rowling's presentation illustrates that failure is part of life. Failure can have benefits as well as drawbacks. Maybe we should "re-frame" our world to something more positive. Where people fail, technical authors, through what they create, are there to help and assist.

Open source economics

In this video, Yochai Benkler explains how collaborative projects like Wikipedia and Linux represent the next stage of human organization.



Is he right? Could the same economic rules be applied to the technical writing projects, where there is a large user base?

The eee pc and the right to remix documentation dilemma

Last week we purchased and received an Asus eee pc 900. Its popularity illustrates the dilemma manufacturers will face in the future, with regard to their user documentation/user assistance.

Background

The eee pc is a ultra portable laptop, which costs roughly a fifth of the price of an Apple Airbook or a Sony Vaio.

It runs on Linux and it was originally designed for children, which explains why it is so cheap. It has a simple interface that provides links to the key software but restricts you from doing much else.

The consequence

Its low cost, low weight and size means the eee pc is popular outside its target audience. The consequence of which is Asus now has a group of users who want to do more with the laptop than was originally intended. They want to add more software and access the Linux desktop hiding underneath.

The manual supplied provides basic, but usable, information on how to use the laptop as originally designed. It doesn't provide any more detail than that. So, as a consequence, a number of Web sites have developed, such as eeeuser.com, which tell users how to access the advanced features.

The problem for Asus is they now have a group of users making modifications to their laptop, based on completely unofficial information. Users have to trust this information is correct - hoping it won't trash their machine.

The dilemma

Here's the dilemma:

Should Asus distance itself from this information? They might miss out on sales to business users if they do.
Should Asus let its documentation be "remixed" - supplemented with additional, more geeky information from users? The information might be incorrect.
Should Asus moderate this user information in someway? They might end up with more support calls if they do.

So what should they do?

Is Twitter a useful tool for technical authors?

A lot of people I know, it seems, are talking about Twitter. Quite a lot of these discussions seem to revolve around the question: is it actually useful?

At the moment, I'm not sure myself. I'm asking myself whether it's a useful tool for technical authors.

So what is Twitter?

Twitter describes itself as a Web site service for people "to communicate and stay connected" through the exchange of quick, frequent answers to one simple question: What are you doing?

In practice, it's also used to communicate with SMS-like messages and as a "RSS-lite" feed.

Why are people twittering about Twitter?

The Internet began with "One to Many" - Web sites that acted as online brochures. Web 2.0 offers "Many to Many" - social networks, YouTube etc. Twitter is seen as part of a new phase: "Many to one".

It's an idea of being able to follow a person's actions and thoughts; to create or be part of a following. That may sound cultish, but the purpose of doing this is to help us recognise patterns. By using Twitter, you may spot trends - people doing the same thing; people sharing the same goal or intention.

According to one commentator, "You can even read exactly what your contacts are reading and recommend you read too. Content in context."

Is Twitter actually useful for technical authors?

1. Twitter may be useful in understanding your users. You could follow your customers' thoughts and action through Twitter. However, this benefit may be more useful for the technical support, usability and marketing departments.

2. Twitter may be a useful way to track the people who set trends that you may follow In the future. These can be experts in their field, imaginative thinkers etc. People like Seth Godin or Dave Winer.

3. Twitter may generate more heat than light. I know of one person who receives one thousand Twitter updates on his mobile phone every hour! That's not content in context, in my book - it's information overload.

In summary, I'm not convinced. Twitter could be useful in a business context as a way of understanding users. It is certainly something to investigate.

PS

I've now created a Twitter account : www.twitter.com/ellispratt

Tracking - One function of twitter that could be useful is the ability to track topics. If anyone in the "twitterverse" posts an update about topic, you can get a notification. This could be a handy way to keep track of certain keywords that apply to you.

Confessions of a technical author - What can technical communicators learn from David Ogilvy?

David Ogilvy was an advertising genius who distilled his successful concepts and techniques into a bestselling book I’ve just finished reading, called "Confessions of an Advertising Man". I wanted to read his book, because I often find it useful to look at other professions and ask whether their ideas could be applied to the world of technical authoring.



So, can a technical authoring company learn any lessons from someone who ran a successful advertising agency? I think so.

The importance of testing, measuring and research

The biggest thing that struck me was Ogilvy’s belief in testing and research.

"The most important word in the vocabulary of advertising is TEST. Test your promise. Test your media. Test your headlines and your illustrations. Test the size of your advertisements. Test your frequency. Test your level of expenditure. Test your commercials. Never stop testing, and your advertising will never stop improving."

"People who ignore research are as dangerous as generals who ignore decodes of enemy signals."

In his early years, Ogilvy had worked for George Gallup Audience Research Institute, which he called “the luckiest break of my life.” To Ogilvy, what mattered were the results for clients, and he saw testing and research as critical to gaining those rewards.

Both technical communication and advertising find it very hard to measure the results of their work. However, advertisers and technical communicators draw different conclusions from this problem:

Advertisers believe that this means they should spend a great deal of time on testing and measuring.

Technical communicators believe this means they should spend little time on testing and measuring - it's too hard.

I think technical authors can learn from advertisers by spending more time on testing. For Web-based content, it’s possible to test and measure some aspects at least, such as the number of times a page is viewed. For this reason, perhaps documentation should be published in most cases on Web servers.

Creating an atmosphere in which partnerships with clients can flourish

Ogilvy "resigned his agency" from numerous accounts where he couldn't see he would be able to get results for his clients. Sometimes this was due to a lack of money available to spend on advertising, a duff product, or a lack of clarity from the client. Ogilvy aimed to take on just one new client per year. His goal was to work for giants such as Lever Brothers, Shell and Bristol-Myers.

The importance of using images

"Dr. Gallup reports that if you say something which you don't also illustrate, the viewer immediately forgets it."

Images are often left out of online Help files, in order to avoid confusing users with the application screens themselves. Maybe it’s time to reconsider this. Perhaps images could be used in a way that distinguishes them from the application.

Promoting the documents

"You can’t save souls in an empty church.”
Documents need to be seen and used, in order for them to work.

There were other statements that, with a few word changes, could easily have been said by a technical author:

1. On the average, five times as many people read the headline as read the body copy.
2. Golden rewards await he who has the brains to create a coherent image, and the stability to stick with it over a long period.
3. The most important decision is how to position your product.
4. A good advertisement is one which sells the product without drawing attention to itself.
5. We prefer the discipline of knowledge to the anarchy of ignorance. We pursue knowledge the way a pig pursues truffles.
6. It has taken more than a hundred scientists two years to find out how to make the product in question; I have been given thirty days... If I do my job well, I shall contribute as much as the hundred scientists to the success of this product.

It was an enjoyable book to read, which caused me to think about the way we work.

Quote of the month

We've just received this nice testimonial from a client:

"I had some basic instructions for my new online application, Opportunity Matrix™, but absolutely no idea how to turn them into a proper help system. Carol at Cherryleaf was able to take my rough notes and turn them into a professional Help file.

She worked through the application, suggesting appropriate changes where I was making assumptions that would have left users confused. Once we were both happy with the file, Carol liaised very effectively with the programmer to make sure that the Help system worked perfectly right from the start.

The information and guidance from Cherryleaf was always top notch, so I always knew exactly where the project was, and what the (quite reasonable) budget needed to be. I shall have no hesitation in using Cherryleaf again, and in recommending them."



Andrew Horder, CEO, Opportunity Matrix™.

Why does this project manager have so many lines on his face?

Notice the man's wrinkles. What have past software development projects done to him?

Maybe this time it will be different.

Maybe this time he can sleep knowing the users will get the documentation they expect. Because maybe this time he'll use a technical author.

Cherryleaf works with developers of software helping them ensure they have the technical authoring resource available to give their users the user assistance they really need. Whether you need either a managed or unmanaged resource, then the people to call are Cherryleaf.

Call us on 01784 258672.

------------
(Testing a new advert)

Poor documentation helps land Microsoft with a $1.35bn fine

Arjuna Krishna Das posted a link to an Information Week article on Microsoft's fine from the European Union.

http://www.informationweek.com/news/showArticle.jhtml?articleID=206900497

"Specifically, the EC ruled that Microsoft was overcharging rivals for the documentation they need to make their server products interoperable with Windows-based PCs and servers. The decision was upheld last year by Europe's second highest court.

Following the ruling, the EC ordered Microsoft to make its technical documentation available to rivals under "reasonable" terms and conditions and to work to make its technologies more interoperable with third-party products."

I seem to recall a presentation a few years back, where someone said that Microsoft was using journalists rather than technical authors to develop the Help for the Microsoft Vista Operating System.

Maybe there's now a ROI case for Microsoft using more technical authors?

Is the "working on screen culture" changing our brains?

The IET's "Engineering & Technology" magazine always contains articles that catch my attention. In the current issue, it includes a piece on Baroness Professor Susan Greenfield's research on how the "working on screen culture" will change the way our brains think.

She argues this is because "our standards of satisfaction and fulfillment may be different". She also argues the information overloaded, screen culture is "not conducive to taking time to think".



Baroness Greenfield is a leading neuroscientist and director of the Royal Institution of Great Britain. She is known for her research into the brain including the effects of Information Technology on the brain cells of the young and the old.

A bit of Web searching brought up some quotations from a speech she made in December 2007.

" (Workers') interaction with screen culture often suggests they are not accessing intuitive feedback (pattern recognition), but acting in the moment, out of the buzz of instant sensation. Excessive reaction to external stimuli, rather than internal analysis can make people prone to being more reckless."

"The answer is creativity. People who can make connections and see what others can't - who can generate those 'Aha!' moments - will see the world and its problems in new ways. This means that as we shift from consumerism to experience to active creativity, there will be a corresponding workforce shift."

"Managers need to lead differently:

Cater for the individual
Guide them in being constructive with risk
Promote creativity"

Although she is looking at how this change will affect the way organisations are managed, it seems likely it would also have an impact on those involved in communication.

Online user assistance can cater for the individual (e.g. segmented, filtered, views of information) and it can guide workers in being constructive with risk. However, it is currently weak at providing a "direct experience" and at promoting creativity. Maybe these weaknesses should be addressed?

New software for technical authors from MadCap Software

MadCap Software has released on details some new products it will be releasing shortly. These include MadCap X-Edit and MadCap Press.

What is striking is that MadCap really does seem to understand the problems technical communicators face in the real world.

One of the issues technical authors often face is dealing with reviews of drafts and dealing with any amendments. If the drafts are sent out as a Word document, your nicely styled document can come back with as a formatting mess. It's partly due to the fact that most users just don't understand Word's Styles features.

Whitney Potsus has posted on her "Connected Content" Blog some handy suggestions on how to avoid this by using some of Word's less well know features ("You turn into Style Gallery Cop and put your documents into lockdown."), but these can create barriers between the reviewer and the documents you want them to review.



X-Edit promises "a document solution for the everyday content contributor that combines both editing and publishing into a single document solution...Send Blaze or Flare topics to reviewers with direct Outlook integration. The reviewer can make edits, changes, and annotations within the topics. When the reviewer is done, sending the topic back is as easy as one click."



MadCap Press seems to park MadCap's tanks firmly on Adobe's lawn. MadCap Press promises the ability to create high-end print documents, such as product brochures. It also promises seamless integration with MadCap's translation tool, Lingo.



I still have concerns that Adobe still really doesn't understand the practicalities of technical communication, that features appear as solutions looking for problems to solve. However, Adobe is the market leader and, as we've seen in IT many times before, it's often the company with the best marketing (rather than the best software) that wins. This means MadCap needs to be good at marketing (which they are), as well as good at development.


I think Author-It will still be a player. They seem to have a strategy of developing a community of advocates and influencers and of disrupting the market. In some ways, Author-It makes FrameMaker and RoboHelp look very old fashioned.

Contract Technical Authors and e-learning courseware developers needed

We've a client who is looking to build a team of e-learning courseware designers or technical authors capable of developing e-learning courseware. This team will work on a MOD IT project it has won, with the project likely to run May (or June) 2008 - November (or December) 2008.

The team will be developing online courseware that will help UK military personnel to use IT hardware. The work will be mostly carried out in Sheffield, although the client might consider 20% off site working.

Candidates need to have some experience of developing e-learning and other training materials for IT equipment. Ideally, you will have MOD security clearance; have experience of developing technical training to the armed forces; plus experience of documenting Windows Server administration and set-up. The contract will be on a 6 month contract basis, with possible contract extensions. Rate is negotiable, so you'd need to tell us your salary expectations.

The ROI of documentation and support

In two conversations this week, the issue of "how do you measure the value of documentation?" has come up.

The benefits of user documentation (reduced support calls, increase in the perceived value of the product, happier customers, better customer retention, increase product usage etc) can be identified, but it can be hard to measure them and accurately quantify the Return on Investment.

Here are two ideas:

1. Conduct a test with two groups of potential users. Give one group your product to install and use for a period without documentation. Give the other group the product with documentation. Ask each participant (a) At what price should this product be sold for? (b) What monetary value would you place on the documentation? For (a), those that had the documentation should value the product more highly than those that didn't. The difference between the two prices gives you one indication of the monetary value of documentation.
2. If you have a Web-based application, use Google Analytics to measure the number and types of people using the Help pages. By placing a value on each visit (e.g. every 2 Help pages visited equals 1 support call avoided), you have another indication of the $ value of documentation. You can use Google Analytics to measure usage by embedding its code into the HTML of each page. Also, some of the Help Authoring Tool vendors offer analytics software for LAN based Help.

Wanted Technical Author, Cambridge, £25K-£35K

#2866 Technical Author, Cambridge, £25K-£35K + Benefits

This is an ideal job for someone who loves working in a fast-paced, innovative, expanding and successful organisation. Our client is a very successful software house based in Cambridge. It is looking for a technical author who can develop online Help, Web-based Help and embedded help for GUIs and APIs.

As you will be writing for database administrators and developers, you'll need to understand the concepts of database design. You will also be working with user experience specialists on GUI design and conducting peer reviews and editing colleagues' work. You also need to have skills in HTML and a Help authoring tool, such as RoboHelp.

Benefits include 25 days' holiday, BUPA healthcare, and stock options.

Contact us for more information.

What will 2008 bring?

What will 2008 bring for you? Perhaps you fancy spending it living in the South of France, sun on your back and 8 weeks holiday entitlement, or amongst the seven hills of Sheffield. If you check our list of current technical author vacancies then we could help you do that.

We've also got vacancies in historic Tunbridge Wells and arguably the greatest city - London. Failing that, there's always the bohemian delights of Hemel Hempstead.

The secrets of effective technical authors

In early 2007, Cherryleaf carried out a survey to find out the challenges technical authors face. We looked at satisfaction levels, the status of authors and what was holding them back, if anything. We also looked at other research on what makes a good writer. We received nearly 500 responses, and we presented our conclusions at the Online Help Conference Europe 2007.

Our objective was to identify areas where there might be opportunities for new training courses and consider publishing a report on what makes a successful technical author.

In general, we found that authors were confident in their own capabilities and the quality of the work they delivered. However, when we asked “What is holding you back?” some fascinating themes came out.

We categorised these as:

(1) office politics (in other words, “nobody loves us”)
(2) project management and
(3) time management.

A key theme coming out from the responses boiled down to authors complaining that their work colleagues didn’t know their value.

When we mentioned our findings to Anne-Florence Dujardin, one of the tutors in Technical Communication at Sheffield Hallam University, she pointed us towards some research carried out by one of her former students in 2002.

This student, Deborah Shapiro, had looked at the personality traits of success in technical authors. In her preliminary study of 223 software technical authors, she had found that effective technical authors had high “openness” and “agreeableness” (defined as “trust of others” and “likeability”), when their personality was measured on the OCEAN personality and PEI effectiveness profiling systems. One of her conclusions was that technical authors should negotiate more, and be more assertive, while maintaining good work relationships. In her words, “skills, language and technical knowledge are sometimes not enough to be an effective technical writer”.

Shapiro’s findings concurred in many ways with our own experiences. It seemed that the solution to being a successful technical author lay not only in being a good writer, but also in being good at positioning, promotion and project management.

What will be the documentation equivalent to Google's OpenSocial?

Google's OpenSocial project is causing quite a buzz at the moment. According to the New York Times, "Its initiative, which it calls OpenSocial, is an appeal to software developers and Web sites to cooperate in adopting a single set of software standards for the little software widgets that can add a social-networking layer to all Web sites. Agreement on a standard would save users from the aggravation of joining multiple networks and save developers from the aggravation of writing code that works only with specific sites. Unlike Facebook’s programming requirements, Google’s use nonproprietary programming languages." It's a move that promises to change social networks like MySpace and Bebo from islands into universal communities. It's not a question of "Will they open up?", but "How much more will they open up?".

See

http://code.google.com/apis/opensocial/ http://www.nytimes.com/2007/11/04/technology/04digi.html?_r=1&ref=business&oref=slogin

There is little technology in OpenSocial that I can see would relate to the documentation community. It's more the mindset in play - whether technical communication will move away from the "island" approach we adopt today.

Online Help Conference Europe 2007 report for technical authors

Last week's Online Help Conference Europe 2007 was a great success and great fun.

1. There seems to be an overall consensus on the future direction of online user assistance/online Help:

- Don't expect Microsoft to lead with new standard Help technologies that we can all adopt.
- A move towards more portal based information support.
- A move towards more collaborative authoring, incorporating content from others.
- Some technical authors are likely to be taking on more of an editing role. Others are likely to be focused purely on writing.

2. On stage, we saw Adobe demonstrating RoboHelp 7, followed by Madcap demonstrating Flare. Madcap probably chalked up a win on the day: its XML, table management and list ordering capabilities seemed to give it the edge.

3. One vendor managed to display a slide containing "it's" instead of "its". There were a hundred technical authors eager to tell him about it at the end of his presentation.

4. There were some very good case studies.

5. You can see our photos from the event at http://www.flickr.com/photos/13696181@N00/tags/onlinehelpconferenceeurope2007/

Our presentation to technical authors

We've finalised our presentation to technical authors at the online Help Conference Europe 2007.

It will be a presentation on our survey into the status of technical writers.

Technical Authors and the right to remix

One feature of Web 2.0 is the idea of the "right to remix". This means giving people the ability to remix your information and services.

This could impact the documentation department in two ways:

1. Your organisation decides to allow others to remix and "mashup" its application or service. As part of this, the documentation needs to available to third parties to help support their (and now your) users.

2. Your organisation develops software as it has always done, but you still want to enable others to modify and remix your documentation.

So what would be the implications of giving others the right to change and republish your user documents? A few questions spring to mind:

- If your document were to be combined with other information (say training material from a third party) would users have a better product?
- How do you ensure all the safety information and legal disclaimers and retained and referenced in the right places?
- Can the document be remixed? Does it need to be modularised?
- Would/could somebody do a better job at presenting the user information than you?
- What would the impact be on support call reduction and product perception?
- Would they add or remove information?

This is an area where some technical authors and documentation managers will need to establish a policy in the future. If you want to encourage remixing, you'll probably need to amend your license and copyright agreements to enable people to do this legally. You'll also need to establish some publishing rules and standards too.

What is the value of user documentation?

One of the biggest challenges for technical authors is to demonstrate and assess the value of the work they do. This is is also true in some other professions as well, such as those in design.

I came across an article by Suzan Boztepe on what exactly constitutes user value and how design can contribute to its creation. Although her focus is on design, some of her findings have relevance to technical communication.

The article is here - http://www.ijdesign.org/ojs/index.php/IJDesign/article/view/61/29

Boztepe identified four major categories of user value: utility, social significance, emotional, and spiritual values.



Typically, the value of user documentation is measured by its utility. Perhaps it should be valued by these additional categories as well?

Technical Authors Conference in Lithuania

We've agreed to be a sponsor of the Writers UA European online Help conference this September. We'll be at the conference in Vilnius, Lithuania, and we'll be doing a short presentation at the start of one the conference days. This will probably be on the subject of dealing with chaotic projects or improving your status as a technical author.

Harry Potter and the deathly Help file

Last night, my family and I went to the midnight party of "Harry Potter and the Deathly Hallows" at The Lion and the Unicorn book shop in Richmond upon Thames, Surrey. This children's book shop is located in a narrow paved alley, so the queue of 100-odd people dressed up as wizards conjured up an image straight out of Diagon Alley.

So what does this have to with Help files? Walking back to the car park, I remembered that, in the distant past, in our time at Digitext, we wrote the text for the Helper character in "Lego Creator Harry Potter". We were asked to write help text appropriate for an eight-year old boy (Lego is for boys, apparently). This lead to issues like, do eight-year olds understand the word "cylinder"? It was agreed they didn't, so we had to come up with an alternative term that would work internationally. We eventually settled on "this type of object is like a baked bean tin". It was a great project to work on.

My 8 year old bounced out of bed, six hours later (groan). How do they do that?

Technical Authors writing test - Free

Free writing test for you to use when you're interviewing.

We offer a free writing test you can use to help you assess candidates. Contact us if you'd like a copy. Note: For prospective employers only - sorry, not available to candidates.

Technical Author Jobs

Just thought I'd highlight three vacancies we're currently working on:

#2738 Technical Author, Maternity cover 9-13 months, NW London, £36K-£42K pa
Our client, a FTSE 100 company, is looking for someone to provide maternity cover for one of its technical authors.The job is a contract for 9 months, which may be extended to 13 months. It might be converted to a permanent job, if the current holder decides not to come back to this role.

#2737 Technical Author, Manchester, £28K + benefits
Our client is looking to a recruit a technical author to join its team. This international company is the leader in developing software for retail organisations. You'll be joining a team that develops user documentation for its main software product. You'll also be involved in developing new ways to produce the documentation, because they want to move towards a structured, component based (e.g. XML), approach to producing Help, training courseware and other documents.

#2655 Senior Technical Author, London WC1, £40K-£42K
Our client is looking for a quick witted technical author to join its documentation team. You'll be documenting a very successful financial software package used by people investigating financial irregularities.


See our vacancies page for more details.

Nine little known secrets about creating great user information

We've written a new article on nine little known secrets about creating great user information.

Please read our article to find out more.

Six biggest mistakes Project Managers make with documentation and how to avoid them

We've written a new article on the six biggest mistakes Project Managers make with documentation and how to avoid them.

They are:

1. They don't communicate their central message and their desired outcome.
2. They are inconsistent or unclear in what they want to say.
3. They don't use the best style of language.
4. They leave insufficient time to write the information, or spend too much time on presentation.
5. They present the information badly.
6. They don't have a manageable way to maintain the information.

Please read our article to find out more.

Free tool for opening Word 2007 documents in Word 2003

Martin Lewis, the money saving expert, has just mentioned Microsoft offers a free tool for opening Word 2007 documents in Word 2003.

If your computer is using Microsoft Office 2003, XP or 2000 programs, download the Compatibility Pack from Microsoft.

You may need to install software updates before the compatibility pack. See the compatibility pack overview section for more information.

New technical author vacancies

We've posted three new technical author vacancies today - both contract and permanent.

We've also added a new self teach training course - RoboHelp X5 training. We'll be introducing a training course in RoboHelp 6 shortly.

News update

Cherryleaf's resident blogger has been on holiday, so it's been a while since we posted any news.

The BusinessWise book was officially launched on the 24th May, and, for a while, it was the 19th best selling book on the Amazon UK Web site. It was the 2nd best selling book in the business category.

The DITA XML training course we launched last month has also been very well received. It enables to extend our scope outside of Europe and into countries such as the USA, India and Canada.

On the recruitment front, we have our first vacancy for a technical author in France, and we have a vacancy in London for a graduate technical author. The latter is a great opportunity for someone looking to become a technical author and seeking that hard to find initial position.

The Technical Authors' dilemma

Thank you to everyone who participated in our survey concerning the status of technical authors and how to improve it. We found out:

They value what they have to offer

They are confident in their own abilities

They believe they're making a contribution

Our survey showed that technical communicators felt they were being held back by factors outside of the core technical writing skills. The primary reasons were:

Office politics

Poor project management by the organization

Lack of time allowed to do the job

Other team members do not understand the role or the value they provide

It reminded me of the Stanford University's Computer Industry Project (SCIP). This surveyed managers of software projects, and it found:

Almost half of all of the respondents were willing to add or delete a feature in the last few days before the creation of the "Golden Master" (in preparation for duplication and shipping), obviously leaving little time for testing of additions or correcting user documentation.

Time-to-market was the strongest consideration while budget and staffing considerations were always the lowest priorities.

Product decisions in more than half the firms were dominated by Engineering. Less than 20% of respondents made decisions based on a consensus between Engineering and Marketing.

Engineers believed that their success in the marketplace was tied to market factors such as features, price and company reputation. They expected bug fixes to come out in dot releases or to be replaced by new functional releases; thus they avoided talking about quality as a competitive factor.

We now aim to focus our report on how technical authors can deal with these issues.

Live STC Web Seminar on 11th April

Dr. Sivasailam Thiagarajan will be presenting "Increasing Interactivity in Webinars" at the STC's next live web seminar on 11th April, 2007, 1:00 pm (EST). It costs $50.00 for STC/SIG members and $65.00 for non-STC members.

The announcement states, "Everyone agrees that an interactive teaching environment is important -- and most expensive tools all too often fall short of their technological promises. So in contrast, Thiagi will share a set of principles and procedures that increase and improve interactivity – affordably!"

See http://stcidlsig.org/webinar for details

Web 2.0 features in upcoming MadCap Flare products

MadCap Software has announced more details on its upcoming "MadCap Feedback Server". In addition to feedback reports on how your readers are using your Help, it includes some of the Web 2.0 features we have been promoting.

These include:

- Web 2.0 community capabilities, allowing readers to add their own comments to existing documentation
- The ability to allow readers to rank the quality of the topics and content

This will make the incorporation of these Web 2.0 capabilities into Help files much easier to implement.

MadCap will also be offering the option of a MadCap Feedback Server hosted service.

They claim "Now you can get feedback on how your audience uses your Help content, allowing you to maximize the effectiveness of your documentation."

Survey into improving the status of technical authors

Cherryleaf has initiated a survey into the issue of improving the status of technical writers/technical authors. You can participate in our questionnaire here:

Survey into the issue of improving the status of technical authors.