Writers shouldn’t code… or should they?

Editor’s Note: This post has been written by Dr. Tony Self of HyperWrite. Tony will delivering DITA training during October at Cherryleaf’s training centre in London. 

Code ninja tshirt flickr creative commons image by juhansoninIn the field of technical communication, an argument crops up from time to time saying that technical communicators shouldn’t have to know anything about XML, because writing is writing, and XML is coding, and never the twain should meet. Dissecting the argument, it appears that the underlying claim is “language first; technology and tools later”.

In many cases, it seems the logic gets a little lost. I have heard statements along the line of “if you can’t string a sentence together, knowing about XML elements and attributes won’t make you a technical writer”, as if those skills are mutually exclusive.

My first observation is that the debate is often poorly framed. XML is not precise enough a term; what does “knowing about XML” mean? XML is an enormous field, covering programming, writing, archeology, journalism, eLearning, spacecraft design, mathematics, chemistry, audio recording, banking, gambling, engine management, and pretty much every field of human endeavour. So in a discussion about the role of XML in technical communication, we need to define what we mean by XML. Bearing in mind that XML is principally a standard for creating XML languages, the XML languages (or applications, in XML terminology) of interest to technical communicators are probably DITA, DocBook, XHTML, SVG, MathML, and XLIFF.

Continue reading “Writers shouldn’t code… or should they?”

The future of technical documentation is more about psychology than technology

In the quest to offer better forms of user assistance, most experts in the technical communications profession propose technological solutions: using XML, intelligent and adaptive content etc. to present essentially the same type of guidance as has been provided for the past 20 years.

We believe there has been a change in the relationship between people and technology, and there needs to be a corresponding change in the relationship between people and the user documentation.

In the past, a lot of technology was unfamiliar, idiosyncratic, expensive and complex; users often became anxious when they used a product. As technology has become part of everyone’s daily lives (particularly Web and mobile applications), people’s relationship with a great deal of technology has changed.

As a consequence, for some types of products and for some types of documents, the traditional approach for technical writing is no longer appropriate.

This means Technical Authors need a better understanding of this relationship – the psychology of users – and understand how they can relate and communicate to users in context.

We are not suggesting that the traditional approach to technical writing should go away completely. We’re also not arguing against technology such as XML and DITA – these are vehicles for delivering content. We’ll still be writing user documentation for scientific equipment and financial systems in the traditional way, as these types of products fit the traditional model. However, even the documentation for these types of products can benefit from the inclusion of some psychological techniques.

Web sites such as voiceandtone.com indicate some of the changes that we are likely to see in technical documentation, but we disagree with some of the approaches suggested on this site for some types of documents, and we feel this site only scratches the surface.

There is evidence from randomised control trials that these new approaches work, although we recommend you carry out your own testing to double check it works for your users.

So having come to be belief that Technical Authors need to incorporate some new techniques into their documentation, what should happen next? One approach is to engage Cherryleaf to provide advice or write documents. In addition, you’re able to discover these techniques through our new advanced technical writing training course. However, the starting point is to recognize the change in the relationship between users and many products, and to recognize the need to change the approach to technical writing so that it’s appropriate to the situation.

The question is, do you agree?

The DITA XML authoring barrier for non-Technical Authors

One of the challenges for organisations moving to a new content management system for their user documentation is selecting an authoring tool that is:

  • powerful enough, and
  • can be used by non-Technical Authors as well as the professional Technical Authors.

Many organisations want staff, such as developers, to be able to add content to the system directly – without having to pass it over to the Technical Publications department. The difficulty lies in that many tools for authoring in DITA and other XML schemas are daunting to those unfamiliar with the underlying principles of DITA and structured content. It’s even more challenging if you’re someone who is only going to write content occasionally.

One approach is to create templates, with defined fields that need to be filled in. Another is to get staff to write in Word, again in conjunction with a template, import the text into the content management system and then map metadata and other semantic information to the content at that stage.

Is it an unsurmountable problem? Should we just accept that writing semi-structured XHTML content (such as wiki-based content or WordPress-like authoring environments) is a better compromise? What you lose in modularity, you gain in having an easy-to-use authoring environment. Alternatively, do we need to recognize we’ll always need specialists who can convert text into the appropriate format – the equivalent of the typing pool or typesetters?

It has bearing on the role and value of Technical Authors. Is it their main value in writing skills, information management skills, editing skills or in using a specialist tool? If the organisation believes “everyone can write well”, then is their value in using software that’s complex and tricky to use?

Cherryleaf XML DITA workshops October 2012 – your opinion needed

We’ve arranged for Dr. Tony Self to host a few training workshops in London this October. Tony is based in Australia, and he also known as Dr. DITA, as he has a PhD in DITA and is the author of The DITA Style Guide.

We’d love your feedback on which XML and DITA training courses we should offer:

  • Should we offer an introduction to DITA, or is everyone now familiar with it?
  • Do you want to know more about publishing from XML?
  • Is there an aspect of XML and DITA you’d like to know more about
  • What course would you want to attend?

Do let us know!

Any user guide, as long as it’s black

At last week’s UAEurope conference (and in this season’s Communicator magazine), Dr. Tony Self suggested how car manufacture can be an allegory for the technical communication profession.

Henry Ford revolutionised car manufacture when his production line replaced the method where cars were hand-made by artisans. Famously, Henry Ford offered the Model T in “any colour… so long as it is black”.

There are parallels in technical communication. Many technical communicators are still clinging to hand-crafted documentation, creating custom layouts and “tweaking” formatting, when new modular methods are vastly more efficient. The age of offering documents in any “colour” the customer wants is over. And just as car manufacture has long since moved to automation, technical communication too must embrace automation, with XML providing the technology platform to make this possible.

I think there is even more we can learn from car manufacturers.

While the Model T was initially a success, Ford was slow to replace it with a new model, and by 1930 the company had been overtaken by General Motors. Ford, had, in effect, created a very efficient process for creating something that almost nobody wanted.  The process was inflexible and it took them a year to introduce the successor, the Model A. So perhaps, technical communicators need to make sure what they produce efficiently is what their customers actually want.

In addition to learning from Alfred P. Sloan (the head of General Motors at the time), we can also learn from today’s car manufacturing processes. Today, many manufacturers use Lean manufacturing. Lean focuses on stripping out waste – if something does not add value to the customer, then it is eliminated. In other words, Technical Communicators need to quantify and demonstrate the value of their documentation to the customer, if they want to use car manufacturing as their model for the future.

The “Beyond Documentation” Webinar videos

Scriptorium Inc has uploaded the “Beyond Documentation” Webinar Ellis delivered back in August 2009. In this session he looked at the future of technical writing and likely changes to the ways in which user assistance is delivered.

We asked:

  • Are we moving beyond documents?
  • If so, what does this mean for technical communicators?

Part 1:

Part 2:

Part 3:

Part 4:

Part 5:

You can see more videos on Cherryleaf’s YouTube channel.


Once more, but with meaning – how will the Semantic Web affect technical documentation and technical authors?

Web technologies expert, John Fintan Galvin, is claiming 2010 will be the year of the Semantic Web, when semantic technologies really take off. If that is the case, how could it be used by technical communicators to deliver better user assistance?

The Semantic Web 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. topics in a Help file, chapters in a user guide, other content, data, people, systems etc.

In the past, we’ve talked about how it will allow for more intelligent searching

However, the Semantic Web also offers technical authors the opportunity to automate the republishing of content (e.g. extracts of a user guide) across the Web – in all the places where this content could add real value to users.

Let’s look at some possible examples:

  1. When someone poses a question in a Newsgroup or user forum concerning “adding a new user”, a summary of the relevant information from the user guide appears automatically in the right hand column of the Web page.
  2. When users from ABC Inc. view the online Help for Oracle 11, they see links to the topics that have been judged the most useful by other ABC Inc. staff.
  3. Users see Beginner, Intermediate or Advanced user information, depending on their individual status or preferences.
  4. When someone raises a Support ticket, a summary of the relevant information from the user guide and/or the latest status on any similar support calls, appears automatically next to the 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. This means looking at your chunks of user information (resources) and asking:

  • What could we connect our content (resources) to?
  • To whom could we connect it?

It also means that the content will need to be stored in a way that makes it possible to categorise the content semantically and to republish the chunks of information in a semantic format.

Ten key issues for CEOs of software companies

At Intellect (the trade association for UK technology companies) yesterday, there was a meeting looking at how UK software companies are faring in this current economic climate. At this event, a panel of software companies CEOs and directors discussed the key issues they are currently facing and the future economic climate for this industry sector.

What struck me was the changes that are happening in Technical Publications complement the changes going on in the overall business.

The ten main issues were:

  1. The reduction in sales.
  2. The need for cash retention and challenges surrounding raising debt or capital.
  3. The continuing difficulties in recruiting good talent.
  4. A high focus on customers and their needs:
    – developing incremental services to existing customers
    – developing more customer business focused services
    – enabling software to connect to other applications
  5. The importance of improving the user experience, such as that adopted by Apple with the iPhone and iPhone Application store.
  6. The move to SaaS (software as a service) and the Cloud.
  7. The emergence of semantic data, collaboration and ontologies.
  8. The move to “mass personalisation” and the emergence of software artisan companies that will personalise mainstream applications.
  9. The growth in mobile phone applications.
  10. The ability to carry out greatly improved analysis of data, leading to greater customer insights.

The big trend in technical communication at the moment is the move towards (XML) single sourcing systems. These break the information into small units of information that can be re-used and repurposed for different circumstances.

This offers a number of benefits, consistent with many of the points listed above:

  • It gives the software companies the ability to develop a range of user assistance documents, each focusing on a particular type of customer and their needs (Points 3 and 7).
  • It means the content can be merged with other content to provide the support information in the right context (Points 3, 5 and 6).
  • With DITA, it helps ensure the support information can written isn a way that clearly enable users to complete tasks (Point 3 again – more business focused services – and Point 4).
  • With DITA, it means semantic data is included in the documentation (Point 7).
  • Content can be published in different media (Points 5, 6 and 8).