Topic-based authoring: The undiscovered country

NT Live Hamlet Many software companies, when they start out, provide user documentation as downloadable PDFs or as web pages. As they develop more products and versions, and as they expand into countries that use different English spellings, the amount of documents can grow until it becomes hard to keep all of these documents up to date.

It’s at this point that they tend to call a specialist technical writing company (such as Cherryleaf) to see if they can fix the problem for them. We find they’ve usually had a brief look at a Help Authoring tool, such as Flare or RoboHelp, and can see that it would solve a lot of their problems. However, they’re often not really sure how to use these tools in the best way.

Although topic-based authoring has been around for over twenty years, for many people it’s a completely new concept. It is, to quote from either Hamlet or Star Trek VI, an undiscovered country. Our meetings with them often end up focusing on the benefits of topic-based authoring.

Topic-based writing is an approach where you write a piece of text (or topics) that typically contains a paragraph or two about a single topic. These topics can be combined to create a page in a PDF document, and they can be organised in a sequence to create an online Help system ( See topic-based authoring page in Wikipedia). It’s a modular approach to creating content. The main advantage of this approach is the topics are often reusable; you can save time by reusing topics across different documents, and you can publish the same content to different media. For example, you could use a topic in training courseware, in a user guide and in marketing information.

As each topic is usually about a specific subject, and has an identifiable purpose, it can also help the writer write more clearly. If you need longer articles, you can build these up from the topics you’ve created.

It’s easy for professional Technical Authors to forget sometimes that many people have never come across this approach to writing before.

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

Webinar: The changing nature of content

You’re welcome to join us on our upcoming free webinar, “The changing nature of content”, which will be held at 7pm (GMT+1) on 24th April 2013.

In recent years, technical communicators have focused on improving User Assistance through new technologies and systems, with the assumption that the nature of the content the tone of voice, the writing style ­ should remain the same. In this free webinar, sponsored and hosted by Adobe, we’ll investigate whether the tried ­and tested writing methods from past decades still make sense today. We’ll look at the reasons why some organisations are “breaking the rules” with the User Assistance they provide.

The registration details will be posted to the Adobe online events Web page in the next few days.

Webinar  21 November 2012 –  Writing policies and procedures: The most common issues, and how to fix them

We will be hosting a free 60 minute webinar called “Writing policies and procedures: The most common issues, and how to fix them” on Wednesday 21st November.

Registration is now open - Register Here

Places are limited.

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?

Writing as a career in IT

Here are the slides from our presentation to Year 10 children at The Matthew Arnold School in Staines-upon-Thames on writing as a career in IT. We looked at the different writing postions in companies, such as Apple, and then looked at the role of the Technical Author/Writer. The class had to write an instruction manual for a new eco-messaging product (aka a typewriter).

New – Affective Assistance and marketing writing services

Cherryleaf’s announced a new service today – Affective Assistance and marketing writing services .

With technology becoming part of everyday life, sometimes the traditional approach to writing user documentation just doesn’t meet users’ needs. It can be the case that the formal and succinct approach to writing User Assistance isn’t right for users of your product or service.

It’s often about adding an emotional factor, being more conversational and less formal. It’s something we call “Affective Writing” or “Affective Assistance”. You can see this approach being used in the online User Assistance for applications such Firefox, where they reported a 13% reduction in the number support calls as a result of adopting this approach.

Consumer technology today:

Consumer technology in previous decades:

See Affective Assistance and marketing writing services .

Assess your technical writing skills – could you be a Technical Author?

Following on from our post Assessing writing skills – a response to “What Does It Mean to Know How to Write?”, we’ve created an experimental test page on our Web site that can help you assess your technical writing skills. The idea is you can compare your skills profile with that of a typical Technical Author:

Assess your technical writing skills – beta

It’s a proof of concept, just for fun etc, but we welcome any feedback on it.
http://www.cherryleaf.com/blog/tag/writing/
www.cherryleaf.com
crawl=CC-MAIN-2014-23
90098
application/http; msgtype=response
sha1:TUYTRZL3KTSTW5GGAFYRYYODWGBSXOBS
<urn:uuid:ba9a97b9-a01b-4dd1-b661-eec84ccac112>
2014-07-24T14:43:44Z
176.32.230.9
sha1:EV2GBXXMVR2NWHAUQU3SLMDM7V4QZNHK
<urn:uuid:a656689e-880e-48f5-aeaf-f52dbbafcf88>
http://www.cherryleaf.com/blog/tag/writing/
length
response
<urn:uuid:0182aa88-2085-40f7-8caf-c7b086038665>
robots: classic
hostname: ip-10-33-131-23.ec2.internal
software: Nutch 1.6 (CC)/CC WarcExport 1.0
isPartOf: CC-MAIN-2014-23
operator: CommonCrawl Admin
description: Wide crawl of the web with URLs provided by Blekko for July 2014
publisher: CommonCrawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf