Will SEO be replaced by AEO (Answer Engine Optimisation)?

Internet psychologist Graham Jones has just posted an interesting Blog called "Search is on its deathbed...bye, bye SEO".

In it he states:

"They (Search Engines) would like us to think that we are constantly "searching" for things online - but we aren't. We are "locating" stuff we already know about, a lot of the time."

"We are merely locating things that we want to find following some offline trigger... Add to that the fact that people are now seeking answers to questions rather than searching for general information, it means that traditional search engines are going to have their work cut out in the months ahead."

This sounds an awfully lot like the behaviour of people using Help files - typically they know WHAT they want to do, but they don't know HOW to do it. They ask questions, in many cases. Navigating and locating become more important than searching.

Perhaps this means the strategies and technologies adopted by technical authors when creating Help files should be adopted by Web developers. Content may need to focused on answering questions, as people migrate towards "answer engines" rather than search engines, such as Google. For software companies, this may simply be a case of adding the content of their Help files to their Web site.

How barcodes could be the technical author's best new friend

The latest mobile phones in the UK are using barcodes to provide one of the first practical applications of augmented reality. It's technology that could see barcodes appear on thousands of physical items - something which would open up new opportunities for technical authors providing user assistance for equipment.

The advert below shows how it's being used today:

Barcode Scanning wit..
Watch the ad...

In the future, users could use their mobile phone to scan a barcode (like the one below) on an item to call up instructions on how to use it.


The consequence would be that technical communicators would need to write content that can be read easily on the screen of a mobile phone (until pico projectors become more widespread).

See also

Will Nokia's new technology reinvent the manual?

Share Life with T-Mo..
Watch the ad...

User documentation - Does it matter?

It's very hard to tell how much user documentation matters to people. One completely un-scientific way is by looking at the messages on Twitter, on any given day, that make mention of it.

Below are some of the messages posted on Wednesday 4th March 2009 that mention documentation.

We've omitted those messages that relate to legal documents and others not relating to user documentation, and we've removed the poster's name. Some people are motivated enough to post a message because they hate the user documentation they are using; some because they like it so much; and others because they hate writing it.

Here they are:

Writing Documentation (sigh)
Documenting the documentation. I should burn these someday.
Rewriting some old VB5 apps that don't have any comments or documentation.
Mired in documentation hell. Can't take any more so off home to flop in front of telly with Pino Grigio.
Yeah, why AREN't you using Groove yet? Now I gotta put all all documentation on some old media like CD or USB
Using Fiddler to inspect S3 requests from S3Fox - now that's faster than reading documentation!!
I like the concept of Capistrano but the lack of documentation is alarming.

Trying to use 2 spot colors with pdflib in PHP. Also trying to think of an even more obscure, documentation-lacking task. Failing at both
When did the Wordpress API documentation go to sh*t?
Pulling together blog content for mvccontrib.. Anyone have a preference on what feature needs documentation in MvcContrib
It's crunch time. documentation review final stages commencing. t minus 2.5 days to finish.

Why I always understand the documentation with mistaken meaning
Another day writing documentation ... good times. (yawn)
Documentation or help sites are next to useless without a search!
Time to brush off the GMaps API documentation, right, right?
Ahh cool. i do have the notation guide, i think i'm just impatient haha. i basically only use it to update documentation!
Writing Documentation
Is working on an endless series of software installs and documentation... Yaaaay...

Wishing Cappuccino actually had some proper documentation and decent tutorials, I suppose it is early days though.
Is back to writing documentation
Listing to Explosions in the Sky and writing documentation. Not exactly Zen meditation, but close enough for this morning.
Cursing inadequate documentation. But going out later for drinks and canapes, mwah mwah

Eurgh! More documentation. I'm frakkin' siock of documentation!
Motivation issues again. Revisiting an old project and rewriting documentation isn't my idea of fun.
Dear Apple, This documentation is not good enough for a parameter called userInfo: "The user info the new timer.". Thank you, Dave.
Reading documentation.
Frantically writing documentation and updating config for a big release... no joy to deploy ;o)

Taking screenshots and writing boring documentation
First I have to finish programming it, then outcome 3 (testing it then 5 test journeys + documentation + screengrabs) then outcome 4
Ok so maybe so far documentation day isn't so hellish.
Taking some Mac documentation we did and creating the same docs for Windows XP. Surprised at what works on XP, as well as what doesn't.
Congrats on the upcoming worldwide Documentation Sprints

Congrats to @add1sun for winning one of the 6 Knight Drupal Initiative winners for documentation sprints. w00t!
In place of proper documentation (coming soon), here are some lengthy release notes for WebComic 1.8 & InkBlot 1.3
Getting intimate with Adobe Acrobat as I create boatloads of documentation for our SACS review next year. Brain turning to mush!
Do it! Joomla has a bit of a learning curve. WP is great for blogging and has its
own CMS as well as a plethora of documentation.

Writing documentation for SMARTY FUNCTION OF DOOM. Seriously, that's what it's called.
Canon Professional Services documentation almost as nice as apple packaging!
Putin mais quand est ce que ces putains de projets open-source fourniront une documentation complète d'utilisation...
Proofreading is a very valuable skill to have when writing technical documentation and specifications

Printing the Admin Guide for Respondus Lockdown Browser prior to installing it for our 8-week pilot test. 12 pages of documentation. yay...
Researching twitter for documentation use -- ideas, anyone???
Writing up documentation on maintaining the RSS Feed. I hadn't realized just how many steps there were until I started writing them down.
JCE is also a lot easier for novices to use which means less documentation.
Just baby barfed!! Doing more documentation!!!
Today is documentation day. Oh joy. How can I make this fun?

Pouring through PayPal API documentation
IT Intervention ep. 4: Sysadmin gets out of control setting up 55 virtual machines with no documentation, standards or even hostnames.
Writing another CMS documentation for a website which is due to go live next week.. 25 pages thus far.
Hello, software documentation writers: QuickStart is two words, separated by a space, that thing beneath your thumb.

Documenting processes. Not exciting, but it's better than not having documentation!
Looking into using the Amazon Seller Central SOAP API but documentation seems a bit sparse, not great for company like amazon
After many tries to undestand values of a MATRIX 3D and iam at the same point. Can't find a great documentation or sth to solve that!
Writing help documentation might be useful but it still sucks
Breaking my balls with springsecurity.. reading its documentation! o/

How Pico Projectors could help the Technical Author of the future

Pico projectors are the latest technology to be incorporated into mobile phones, and their introduction could provide technical authors with a new way of delivering technical documentation. They could be of particular interest to those writing documentation that's used in factories, workshops and other areas unsuited to computers and paper manuals.



Pico Projectors are miniature low power projection modules. They are able to produce full colour, high-resolution images up to 1.5 metres onto any surface. Their size means they can be embedded into mobile phones, with the promise that people can show their friends what they've recorded using their mobile phones and other videos, such as music videos of their favourite bands.

They can be used to project other information too, and this could well be user documentation. The aircraft engineer of the future could project the maintenance instructions next to the item they are handling - on a nearby object or wall.

At present, they work best in subdued lighting, but the Lumen output from this technology will increase in the near future.

26 March DITA Workshop - 75% of places now booked

75% of the places our special DITA workshop on the 26th March have now been taken.

There are still some places available at the moment, but this training workshop is now likely to sell out.

Why bother with user documentation in recessionary times?

Although many organisations see user assistance as a "good thing", it's not immune to the belt tightening that many organisations face in times of difficulty.

Business expert Mike Southon recommends that in recessionary times, organisations should focus on getting sales from existing customers - so customer retention becomes ever more important.

There's a virtuous circle of a customer finding user assistance helps them and becoming a loyal and happy customer. Whilst user documentation can help with the perceived quality of a product before the sale, its key value is in keeping customers: customer retention in marketing-speak. It's the philosophy of Toyota and others - the focus on quality and customer service.

Chris Bose of In Press PR Ltd, told me that recessions are the times when market share changes. This is why successful companies reduce their advertising spend, but never cancel it. They know that when the economy turns and business improves, they'll get more sales than the competition - more sales than they ever did before, most likely.

Recessions are also often the times of greatest technological change. The Great Depression saw the wide-scale introduction on electricity to houses in Britain, and, today, we're seeing significant developments in Help Authoring software. Those companies that can adopt these new developments in user assistance now will be able to differentiate themselves from their competitors - something of importance in these highly competitive times. As the economy swings upwards, this competitive edge will make a difference in sales.

However, it can very hard to measure the effectiveness of documentation. Again, this is where recent technological changes come into the place. A number of Help tools now enable you to measure how many people accessed your documentation, whether it assisted them or not, as well as many other useful measures. Indeed, Web based user documentation can be the trick to increasing your Search Engine rankings (but keep that a secret!).

It may be that you can provide better user assistance for less money. You may find you save on translation costs, lower support calls and lower printing costs.

Perhaps the question should not be "why bother?", but "how can we do it better?"

Twittering Technical Communicators

The technical writing community is starting to take Twitter to its heart. The people below are a mixture of technical communicators and entrepreneurs (plus one celebrity - Stephen Fry) whom we're following.

Updated: 24 February 2009

If you're just starting out on Twitter this may give you a headstart on who to follow:

Get your twitter mosaic here.

Should you appoint a Director of Content?

We ask the question, because a need for a "Director of Content Marketing" is being discussed by a number of Web 2.0 related blogs.

According to Wikipedia, it is an umbrella term encompassing all marketing formats that involve the creation or sharing of content for the purpose of engaging current and potential consumer bases. In contrast to traditional marketing methods that aim to increase sales or awareness through interruption techniques, content marketing subscribes to the notion that delivering high-quality, relevant and valuable information to prospects and customers drives profitable consumer action.

Should that role be extended to cover technical documentation? Will a the role of "Director of Content" appear in the future?

See Warren Sukernek - Our new Director of Content Marketing

How Content Marketing Will Shake the Tree

How valuable is product documentation?

We received this email from a Documentation Manager, yesterday:

"As times are getting tougher, we've been challenged with the age old question of "how valuable is product documentation?" - e.g. prove your worth basically!

Certainly, we know that for a product to be marketable and successful, it needs documentation to support the end user.
However, I am currently trying to gather more information specifically about GUI product online help:
1. How often is it really used? I know every product is different so usage will vary - but in general how do user's feel about it?
2. Do user's require it to be context sensitive - or can an e-support Center with all documentation available for searching suffice?
3. What is the current trend for online help structure? Scenario based instructions, quick snippet videos, etc.

Ideally, I'm trying to gain insight into the ROI for documentation efforts spent. If you have any information from past research on the value of documentation, I'd be really grateful if you could share it.

So how would you respond to this challenge?

Could Zuberence be used in technical documentation?

Zuberance is a hosted service for encouraging user generated content. Although aimed at creating "Brand Advocates" or "Customer Evangelists" and a "Volunteer Salesforce", maybe it could be used to create user generated support. What do you think?

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.

There's the tribe, where's the technical author?

I've just downloaded Tribes Q&A, a fan book inspired by Seth Godin's latest book "Tribes: We Need You to Lead Us". The book talks about the basic need humans have to connect with other human beings from a social and a commercial perspective.

There's one sentence that stood out for me: Connecting people and giving them a place in the world IS (what makes you a living).

I immediately thought, this affects technical authors. They connect people to information, rather than people. They help people find their place. They play a role in building and maintaining an organisation's tribe. They show there's more to the supplier-customer relationship than the moment of the sale.

The user assistance that technical authors provide is part of the longer term relationship that leads to customer loyalty.

The book asks and answers some great questions:

- How does a tribe awaken its “sheepwalkers"?
- How does the leader of the tribe walk the fine line between being inclusive and allowing the tribe to become a democracy? Between setting direction and becoming an autocratic factory?

It raised some questions in my mind:

- Does Cherryleaf have a tribe?
- To which tribes do you belong?

Basics of Technical Authoring self-study training course page goes "live"

We’ve just uploaded the files and activated the Buy link for "Basics of Technical Authoring - a self paced, home study training course". In other words, we can now take orders from people wanting to purchase it.



This course teaches general, basic technical authoring principles and writing approaches suitable to user documents. It describes the entire documentation process: planning, writing, editing, indexing, and production. This book focuses on documentation for computer hardware and software. However, many of the concepts described apply to other forms of technical writing, such as writing about manufacturing environments, medical and pharmaceutical topics, and science.

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

Technical authors tackle "The curse of knowledge"

If you’ve ever struggled to explain something to someone considerably less expert than yourself, you may have experienced "The curse of knowledge". It's a curse that technical authors resolve everyday, although they may not know they've been doing it.

It's a phrase that comes from a great book called "Made to Stick" by Chip and Dan Heath.


They state:

Lots of research in economics and psychology shows that when we know something, it becomes hard for us to imagine not knowing it. As a result, we become lousy communicators. Think of a lawyer who can’t give you a straight, comprehensible answer to a legal question. His vast knowledge and experience renders him unable to fathom how little you know. So when he talks to you, he talks in abstractions that you can’t follow. And we’re all like the lawyer in our own domain of expertise.

Here’s the great cruelty of the Curse of Knowledge: The better we get at generating great ideas - new insights and novel solutions - in our field of expertise, the more unnatural it becomes for us to communicate those ideas clearly. That’s why knowledge is a curse.

In the book, there's reference to some very interesting research by Elizabeth Newton on communication - involving tapping out a song to someone and seeing if they can recognize it.

Their solutions to the problem coincide with many of the principles technical authors use.These solutions include:

Start with a beginner's mind.
Make it simple by taking "knowledge" and refining it down to a core concept.
Don't paralyse readers with too many choices.
Help people understand and remember by using concrete examples and avoiding abstract concepts.
Get people to act (in the sense of doing something).

It's a great book for helping technical authors understand and communicate their value - something, ironically, they are generally quite poor at doing.

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.

Microsoft Style Guide for Windows 2007?

We received this email yesterday:

Microsoft Style Guide for Windows 2007
Do you know whether such a thing exists or whether you know of anything else that might help? I am updating the help for our new product and it uses a Windows 2007 ribbon style GUI but I don’t know what all the elements are called.

The Microsoft Guide of Style was written in 2004, so it's a case of looking elsewhere. We suggested the Microsoft Office Word team blog, which has some useful information on this.

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.

DITA - Slaying sacred cows or burying problems?

There have been a number of posts recently on whether some commonly accepted best practises in technical writing are actually needed these days. This has come about as people question how they can develop the DITA standard to handle things like lead-in sentences and stem sentences.

These don't fit into the standard, and a number of people are now saying we don't really need them. This is very convenient for the DITA standard - it makes the problem go away.

My concern about this is that there has been research that shows "Lexical repetition, cohesive devices and other textual features will need to be incorporated into specifications right from the start, i.e. during the document planning stage." Indeed, we wrote a blog post on this research back in December.

I trust the needs of the reader will be balanced with the needs of the writer when coming up with an efficient writing standard that works for the reader.

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?

Six ways to add Web 2.0 functionality to your manuals

This is an end of a long day post, so forgive me if I miss anything obvious. Here are some suggested actions and ideas for creating Web 2.0 technical documentation:

1. Put your documents on the Web, as Web pages.
2. Create a link to the Web version on folksonomy/tagging sites such as Digg, Technorati and del.icio.us. Describe your content on these sites (using tags).
3. Consider aggregating/incorporating content from other sources into the online version. This could be content from other departments, such as support, or external content. You can use RSS feeds to acquire this content.
4. Create a RSS feed for your content. This can help users be aware when content has changed, and help them re-use the content elsewhere. You could use Feedburner to do this.
5. Create a Twitter account and link your RSS feed to this account. This means users who are also Twitter users can receive your updates through Twitter. You can use Twitterfeed to do this.
6. Consider enabling users to add comments to your content. Some Help authoring tools allow you to add this functionality. Others allow you to embed this functionality from elsewhere. Another potential way to do this could be by using the Adobe Air viewer.

What about wikis? Wikis can be a good idea, particularly if you want to use content from development staff. However, you need to consider how you control and approve content and how you create printable manuals.

What is Web 2.0?

We 2.0 is name for a collection of Web technologies that can be summarised enabling conversation, aggregation and collaboration.

Why add Web 2.0 functionality?

That's a whole conversation in itself, but the benefits include establishing a better relationship with your clients and prospects and getting others to write some of the content.

Have I missed anything out?
Should you take this advice?

Ten Challenges for Technical Authors in the Network Age

The Supernova 2008 conference is currently running in San Francisco - on the theme of "the Network Age". Professor Kevin Werbach has outlined ten challenges:



"In the Information Age, computers and communications networks produced a global village and astounding gains in economic productivity. The Network Age incorporates those advances into an environment where anything connects to anything, anyone to anyone, anywhere, anytime. We’re not all the way there yet, but we’re far enough along to start seeing the effects... The Network Age poses ten basic challenges for all of us interested in the future of technology, media, and communications:

Scarcity and Abundance
(Both are sources of value, yet they cannot coexist.)

Choice and Coordination
(Users are in control, but don’t they need guides to avoid being overwhelmed?)

Aggregation and Fragmentation
(Network effects mean that the big players get bigger, but at the same time, markets increasingly specialize and personalize.)

Stability and Disruption
(True innovation requires disruption, but disruption can be painful and costly, especially where investment and trust are significant.)

Behavior and Rationality
(People don’t always act according to models of rationality, especially when connected to one another, but our economic frameworks assume they do.)

Complexity and Simplicity
(Complex adaptive systems produce emergent behavior and growth, but simplicity is a virtue… in both life and information technology.)

Openness
(Everyone agrees it’s good, even essential in a networked environment, but no one can say what exactly it means, or how much openness is beneficial.)

Governance
(How much do networks and their users need to be managed or protected, and where do those controls come from?)

Scale
(The local is different from the global, whether the subject is enterprise collaboration or usage patterns or cloud computing infrastructure.)

Sustainability
(How to build organizations and systems that endure, especially in a world whose delicate ecology is itself a form of scarcity.)"

Are these the challenges we will face in the future?

Is this video on advertising-customer break up also true for technical communication?

Brian Solis, Principal of FutureWorks PR and New Media agency in Silicon Valley, has posted a blog on the need for organisations to listen directly to the needs of the customer.

Solis states:

"You can’t manage a relationship, you need to be a part of it, fully engaged...

...If a conversation takes place online and you’re not there to hear or see it, did it actually happen?

The customer comes first, and if we fuse sociology, social media, customer service, relationship marketing, experiential marketing, and traditional marketing, we’re creating a new formula for outbound influence and fueling a new generation of brand ambassadors and loyalists."

Is this also true for technical communication?

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.

Trends in Technical Communication - Peering into the crystal ball

I'm starting to think about a conference presentation I have been asked to make later this year. Sometimes, our talks are about "big picture" issues, such as "what makes a good technical author?" or "what's the value of documentation?", and I'm currently considering whether I should talk about the future trends in technical communication.

The two current trends in technical communication

There seems to be two trends in technical communication, at the moment.

The first is the move away from a craft-based approach to creating documentation, and a move towards a more "engineering" based, methodological approach. It explains the interest in and move towards single-sourcing, XML, DITA and such like. It promises more efficient writing processes, faster "time to market", but little change in what the end user actually receives.

The second trend is the adoption of Web 2.0 technologies to provide user assistance. I've heard it also called "free documentation", "right to remix", the "democratisation of documentation" and "tech writing 2.0". I don't think any name has stuck yet, apart from the generic "Web 2.0". It's a trend that promises a major difference in what users actually receive as user assistance.

We describe Web 2.0 as having three main themes: the aggregation of knowledge; collaboration on content creation; content as conversations (and linked to that, the wisdom of the crowd).

When I presented on Tech writing 2.0 at the end of 2006, the major developments mostly related to the aggregation of content across the Web. Today, the biggest developments seem to be with conversational content.

It's content that is, today, being created away from the Technical Publications department.

What does this mean to technical communicators?

I think the questions technical communicators should be keeping in the back of their mind are:

1. Should I be adopting and embracing these trends?

For some organisations, particularly those with a small user base or a small authoring team, the answer is NO. It's hard to see where the participation and the benefits will come from. However, will that mean their documentation will look inferior to more mainstream software?

2. Can these two trends be unified?

Will these trends converge? Will Web 2.0 content rip apart all those carefully laid plans for a single repository for all your content?

3. Who will take on the role of editor?

Who will keep all this information in order? Maybe you will need to take on the role of an editor.

The correct answers, I believe, have yet to emerge.

What else should I be reading apart from the Cherryleaf blog?

Take a look at these articles:
Why Do People Write Free Documentation? Results of a Survey by Andy Oram
The State of Free documentation, by Adam Hyde
The state of free documentation by Anne Gentle

What do you think?

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?

Follow the thoughts of technical communication experts

We've created a Web page that aggregates the messages from some of the leaders/pioneers in the technical communication sector.

You can view the Web page here

How will the Semantic Web affect user documentation?

Tim Berners-Lee said, in 1999:

I have a dream for the Web [in which computers] become capable of analyzing all the data on the Web – the content, links, and transactions between people and computers. A ‘Semantic Web’, which should make this possible, has yet to emerge, but when it does, the day-to-day mechanisms of trade, bureaucracy and our daily lives will be handled by machines talking to machines. The ‘intelligent agents’ people have touted for ages will finally materialize.

Today, the Semantic Web means that data may be re-used in ways unexpected by the original publisher.

What does this mean to technical communicators?
Is the Semantic Web "a good thing" for technical communicators?

Twitter revisited

Here is graph comparing the use of words in Twitter that are commonly associated with the field of technical communication.

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.

Issuu - A Web-based pdf viewer for technical authors?

Issuu is a Web site that allows you to upload magazines or newsletters and then view them as interactive, magazine-style online publications in your Web browser. It's a free service and has been described as a YouTube for magazines. There are a few manuals on it already.

The Issuu document is presented in a way that looks similar to a magazine. You can easily flip through it, using the arrow buttons, page numbers, the 'dock' below it, or the index.

Readers can comment on the documents, bookmark them, add authors to favourites or subscribe to them in a RSS newsreader.

Although it is geared towards glossy magazines, it could have uses for technical communicators. My initial thoughts are where you want readers to look and comment on a document, but you don't want them to download it, or where you want your document to look striking visually. The navigation isn't perfect, however.

Zen and the art of Help files

I've finally received my copy of Garr Reynolds' excellent book, "Presentation Zen". This book is about creating better, clearer presentations in a Zen-like frame of mind. If you have seen any of my presentations, then you'll know I prefer his photo-image style to the bullet point style that is more commonly used.

I would argue that "Presentation Zen" contains ideas that are also relevant to technical communication.



So how can the approach espoused by Garr Reynolds be applied to the online Help and the user manuals that technical authors create?

He proposes presenters connect with the audience to inform in a meaningful, unique moment in time. His philosophy includes these beliefs:

- Prepare with three words in mind: simplicity, clarity and brevity.
- Simplicity leads to clarity and can be obtained by reducing to the nonessential.
- Target both the readers' creative and logical sides of their brain.
- Start with the beginner's mind.
- Ask the right questions.
- See the big picture.
- Design and layout are important.
- People remember visuals better than lists.



I believe most online Help (that has been developed by a professional technical author) has most of those boxes ticked. However, I think there are some areas of Garr's ethos that are often missing from user documentation:

1. The "art of being completely present" when delivering the content. The last thing on a user's mind when they call up Help or read a user manual is a Zen-like state of mind! The way in which Help is normally delivered to the user is frankly weak - requiring them to press F1 and admit failure.

2. Targeting the reader's creative side of their brain. The technical author's content is nearly always logical. It's rare, too rare perhaps, to have content that encourages play or experimentation. Manuals rarely reveal any passion in the writer.

3. Seeing "the big picture". I think technical authors do see the big picture, but sometimes miss out on explaining the big picture. Perhaps there's a pressure to dive into the nitty gritty of describing tasks? There's clearly a need from users to understand the big picture. I know someonewho makes a tidy living "explaining anything in less than ten minutes". He does this on paper, within the confines of an A3 poster.

I recommend technical authors take a look at this book and consider whether they could apply these ideas to their work.

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?

Could technical authors help you get closer to your customers?

BBC Four is currently running a series on advertising called "Selling Power", which is followed by the rather good "Mad Men" drama about advertising people in the 1960s. In "Selling Power", someone (I can't remember who) argued one of the benefits of modern day, Web-savvy, advertising is it enables companies get closer to their customers. I took that to mean it enables them to both get a better understanding of their clients and to create customer loyalty to the brand.

Well, I know another way of getting closer to your customers. It's through your technical author. He or she stands as the customers' representative, giving developers feedback on what works and doesn't work. He then explains the product in the language of the user.

I wonder if any organisation has its technical authors in the same department as it has its copywriters and advertising directors?

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.

RoboHelp Packager for Adobe AIR

Back in the Autumn I posted about Abobe Air and how it could be used to provide a new medium for online Help. Today, I came across RoboHelp Packager for Adobe AIR, which is currently in beta.

It converts RoboHelp 6 or 7 generated WebHelp files into a single AIR file, which can be shipped to the user as an alternative to WebHelp. Air is similar to PDF, in that it will work across different operating systems in a consistent manner.

Will Nokia's new technology reinvent the manual?

Nokia is developing new technology which could reinvent the user manual as we now know it.

Combining a mobile phone's camera with image recognition software, location tracking technologies and improved processing speeds, Nokia intends to provide users with "augmented mobile reality". The goal is to enable anyone to look at the real world through their camera-phone and virtually augment it with information based on parameters such as where they are or what they're looking at. Nokia suggests "you will for example be able to look at a particular building and get all sorts of information about it; or a given shoe model at a shoe store".

The technology works by simply pointing to an object with your handset's camera and either taking a picture of it that is used to apply intelligent pattern matching technology or moving your camera around and obtaining a real-time match of the image. The phone will retrieve this information from the handset or from servers via the Internet. The network uses location tracking technology to know where you are.

In addition to providing tourists with information on building facades and shoppers details on retail products, this concept could also be used to provide users and maintenance engineers with user assistance and instructional information.

There could be a time where you open up the bonnet of your car, point your mobile phone at the engine to (a) identify which part is which and (b) call up instructions on how to remove and replace a particular part.


The technology was first demonstrated by Nokia in October 2007, although it could be a number of years before it is included in publicly available handsets.

Better than Free: User Documentation?

Kevin Kelly has posted an interesting post called "Better Than Free." It's about what succeeds in a market where most assets are free.

"The internet is a copy machine....When copies are super abundant, they become worthless. When copies are super abundant, stuff which can't be copied becomes scarce and valuable.
When copies are free, you need to sell things which can not be copied.
Well, what can't be copied?....

There are a number of other qualities similar to trust that are difficult to copy, and thus become valuable in this network economy... We can start with a simple user question: why would we ever pay for anything that we could get for free? ...From my study of the network economy I see roughly eight categories of intangible value that we buy when we pay for something that could be free."

Kevin argues the eight generative qualities add value to free copies, and therefore are something that can be sold. They are:

• Immediacy
• Personalisation
• Interpretation
• Authenticity
• Accessibility
• Embodiment
• Patronage
• Findability

How does this relate to user documentation?

Documentation is often very easy to copy in itself. However, documentation can also be a mechanism to help create these "generatives" in a product.

Furthermore, these generatives sound familiar to anyone who has ever attended a documentation conference debate on the future of technical communication; in particular: Immediacy Personalisation, Accessibility and Findability.

Perhaps the future value of technical documentation lies in these eight factors?

New how-to/instructional video sites

Another how-to/instructional video site has been launched - Howcast. The video player on the site lets you jump to different chapters or steps, lets you zoom in for a better look, and provides the transcript as well. Viewers can add comments in the form of tips, warnings and facts to each video.

Howcast joins Expert Village, 5min, WonderHowTo, techtutor.tv and Instructables .

The user assistance skill set

We were having a clearout when I found a handout from a presentation made by Joe Welinske on the user assistance skill set. Although this presentation must have been made four or five years ago, it still rings true today.

According to Joe's survey, the skill set of for user assistance comprises:

• Writing
• Editing
• Indexing
• Quality assurance and testing
• Graphics development
• Information design
• Usability testing
• Task analysis
• Localization
• Coding Help
• Coding Web content
• Programming

The most valued user assistance skills were:

Writing procedures (92%)
Experience with tools (85%)
Writing reference information (79%)
Interviewing (74%)
Coding HTML (72%)

As Joe put it, you get paid for the writing.

What does single sourced content mean to readers?

Lyn Gattis kindly sent us a copy of her PhD dissertation over the Christmas break. She used some content from the Cherryleaf Web site in her dissertation, which looked into the comprehensibility of single sourced technical documents.

In her dissertation, Lyn painted this scene:

"Judi Greene is evaluating the capabilities of 'CommonText', a new single sourcing application. She recognizes single sourcing's potential for greater efficiency in a rapidly changing publishing environment, but questions whether single sourcing truly serves readers well."

This imaginary Documentation Manager's concerns are:

• How well can single sourcing methods accommodate rhetorical variations that would improve reader comprehension?


• Is highly standardized text appropriate for cross-cultural audiences?


• Does removing meta language, particularly cohesive devices, from single sourced texts significantly affect comprehension for specific groups of readers?

The key result from Dr. Gattis's study indicates that readers are more likely to comprehend texts with lexical repetition (which are often sacrificed in single sourced documents and online Help files). When texts are cohesive, readers are more likely to consider information to be clear, well organized and easy to follow.

Dr. Gattis's conclusions coincide with future trends we and others have hypothesized:

• Human editorial oversight will continue to be essential for comprehensibility, even when composing is partially automated.


• Technical Communicators may need to specialize on different tasks within the team.

In addition, she argues:

• Documentation teams will need to resist system efficiency as an overarching goal.


• Lexical repetition, cohesive devices and other textual features will need to be incorporated into specifications right from the start, i.e. during the document planning stage.


• Organizations have several options for integrating cohesive devices into single sourced texts. However, these options may reduce writer productivity.

One solution is to build cohesion into templates, boilerplate documents, style sheets, DTDs and/or schema.

Interestingly, this was the approach by RePublico software (now defunct), and are capabilities being introduced into AuthorIT and similar tools.

Can technical authors be "part of the conversation"?

I was reading a post by an acquaintance of mine, William Buist, on how advertising will need to change in the future.

He wrote:

"At a recent conference Mark Zuckerberg, the 23 year old boss of Facebook was talking to 250 or so “middle aged” advertising executives about the news ways that Facebook envisaged advertising developing. His thoughts are indeed interesting. “For the last 100 years media has been pushed out to people, but now marketers are going to be part of the conversation”. That phrase - 'Part of the conversation’ caught my eye. What does it mean to you?"

Surely technical communicators will face a similar challenge - to be part of "the conversation" in the connected Web 2.0 world that's emerging.

William posed some questions for advertisers that can be also posed to the technical authoring community:

- If we are going to be part of the conversation, will we be let in?
- What would make people do that?
- Once we are in the conversation how can we best add value to that conversation?

Other questions arise:

- Will engaging with a community in a social networking environment create a new and better way of providing user assistance?
- Will social networks create an opportunity for technical communicators to eavesdrop a conversation as well as take part of it?
- Will the rise of streaming websites both for audio and video such as YouTube enable technical communicators to be more viral in their efforts to provide effective user assistance?
- Will technical communicators see snippets of their technical information embedded in other people's Web pages?
- Might the lines between technical support and technical authors start to cross over?

Where do this all go?

William concludes:

"The advertisers who get this right, who deliver to us the right products or service at the right price at the time we need will clean up. The ones who get it wrong could considerably destroy the brands behind the advertising. One thing is certain, the face of advertising is changing. The need for more contextual advertising is clear and the willingness of brands and businesses to engage at the conversation in a social networking environment is becoming more paramount."

If you substitute "technical communicators" for "advertiser", then we could probably say the same thing.

Making interactive "How To" videos

Hypertext functionality comes to videos.

Asterpix is an interesting Web site that enables technical communicators and trainers to create interactive videos.

This brings Captivate-type functionality to TV/YouTube videos.

You can add hotspots and hyperlinks to areas of the video, allowing viewers to get more information on objects of interest during video playback.

Viewers can also navigate directly to specific scenes that contain objects of interest without having to watch the entire video.

This may address some of the disadvantages with video based instruction: having to sit through the whole video; no interactivity; poor search and skip; and no drill down, "minimal manual" capabilities.

(Thanks to Laura Jaffrey).

Adobe to launch a new Help browser?

At yesterday's Ticad conference Adobe's Mark Wheeler (MD Northern Europe) spent time in his presentation talking about Adobe Air. Mark suggested it could be used as a new Help (or document) viewer technology.

Air enables anyone to build a simple desktop application. Used a Help browser, it can integrate content residing on the PC with other content residing on the Web. User comments/annotations could be displayed at the bottom of the page. Air also offers the abilty to embed two way audio , call up an extract of a video, and include Flash files, PDFs and HTML.

Air is currently in beta and is available from labs.adobe.com

He also talked about Acrobat files that can be "turned off" should you wish users no longer to view the file.

And RoboHelp? Mark said very briefly it remains a core product, but didn't say anything more about it.

"The smartest people work for someone else"

Here's some extracts from an article by Forbes' Rich Karlgaard:

" 'No matter who you are, most of the smartest people work for someone else.'

Say again? What organizational leader will admit he can't hire the smartest people in the world? This provocative statement was first made by Sun Microsystems' Bill Joy in 1990... It's better, Joy said, to create an ecology that gets all the world's smartest people toiling in your garden for your goals. If you rely solely on your own employees, you'll never solve all your customers' needs.

What Joy said in 1990 is unimaginably truer and more powerful in 2007... Your job, as a leader of an organization, is to tap into this mass of innovators, investors and consumers. Your job is to enlist as many smart people as you can to pull your company in the direction you want it to go. Your job is to learn and adapt as fast as the digital networks will let you. Can you?... It is not the wisdom of crowds. It is finding one smart person on the outside. If collective wisdom is what you want, Joy's Law covers that, too."

Interesting stuff.

Podcast on Cherryleaf and Technical Communication

Ellis was interviewed yesterday for one of the "ITauthor" podcasts. To listen to the conversation, visit http://www.itauthor.com/wordpress/2007/11/14/itauthor-podcast-12-november-14th-2007-ellis-pratt-cherryleaf/

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.