Blog Archives

Minimalism at Tekom tcworld 2012

I’m attending Tekom tcworld 2012, in Wiesbaden. Jang Graat is about to present a session called, “Write less – say more. The added value of minimalism”. I’ve read quite a bit about minimalism, and am looking forward to hearing Jang’s ideas on applying the methodology to make things easier for our readers.

This is the blurb for Jang’s session:

In the internet age, users are swamped with information. Instead of telling users what you know, you should literally put yourself in their position and figure out what they need to know. And then see how you can make that information available as concise and clear as you can. After the initial extra effort, it will make your job, and your user’s lives, a lot easier and more productive.

The principle of minimalism is fairly simple, and is not changing much. Jang plans to give us the basic principles and what they mean.

The movie

We started by watching a clip of a Vin Diesel action movie, where couldn’t find in the user manual what his car could do. Jang says Vin Diesel is our typical user. The typical user is in an emergency. They need one answer to one question. And if they don’t find the answer, the world is going to end.


Many of us are still writing lots of documentation that people will never need. Our users are suffering from information overload. A lot of it is useless. The good stuff is hidden by layers that most people will never use.


Put there only what the user needs. That’s minimalism.

John M Carroll at IBM took the minimalist practices, already applied in interior design and other disciplines, and applied them to technical documentation.

WilliaM of Ockham (philosopher in 13th century) said you shouldn’t introduce a new element unless you really need to. This is Ockham’s razor. Minimise the number of assumptions you make, and build your theory around that.

You make sure you have the minimum set of tools that you need for a certain situation. The last four words are important. Compare the set of tools a repairman takes up onto a roof. He won’t take his torch, for example, if it’s daytime.

Advantages of minimalism


  • Improves the signal-to-noise ratio: Removes noise, maximises signal
  • Minimises cost
  • Minimises effort, for the technical writer, and for the user trying to find information
  • Minimises support effort
  • Maximise clarity


The most important thing is: Topics.

Typically, documentation answers 3 or 4 questions at the same time. For example, let’s say you want to add a row to a table in Word. Find the topic in the help – it typically starts by describing tables, then tells you there are a few ways to add a row, and also tells you about columns.

Rule of minimalism: One topic answers one question.

The most important question you can answer is: how do I do this. If you want to, you can add extra topic(s) that describe how stuff works.


Give your content a very clear, recognisable structure. The user can get used to this structure, and then find information easily. Example: Recipe books. This is a minimalist practice, because it minimises the user’s effort.

Amount of content

Minimise the number of words you write.

Remove repetition, for example don’t repeat the title text in the introduction of the topic. Don’t use words like “first”, “then”.

Use annotated diagrams where possible, instead of lots of words to describe the location of things.

Controlled vocabulary

Control your language. You can use a specific type of controlled English, or do it yourself. This minimises ambiguity.

Use separate steps, not joined by “and”, unless the user has to do two actions simultaneously.


Maximise safetyl For example, in documentation about machinery, safety is a big issue.

On the other hand, don’t exaggerate. Exaggeration has the effect of devaluing the message. That is unsafe. (The machine industry has a strict classification of the severity of messages.)

Don’t have too many warnings, errors, cautions. That is not safe.


Jang described how minimalism maximises efficiency, making it easier to meet deadlines. Production becomes more efficient, because there’s less to produce. (Think, printed manuals.) You minimise the time people need to find information, thus maximising their efficiency.

Focus on users

This is the main point that Jang wants to make: Focus on the users. This is the main lesson in any approach to minimalism. Put yourself in their shoes when you decide what to write.


Jang has a pleasant, restful speaking style. His slides were pleasantly minimalist. Thanks Jang.

Augmented reality at Tekom tcworld 2012

I’m attending Tekom tcworld 2012, in Wiesbaden. The next session sounds like fun: “Is Augmented Reality the Future of Technical Documentation? ” by Juergen Lumera.

Here’s what Juergen wrote in the blurb for his session:

A couple of years ago Alan Brandon asked in an article about an Augmented Reality research project at the Columbia University the question: Is augmented reality the future of technical documentation? He did not really answer the question but he showed a huge potential of that technology. The research project did not change the technical documentation world at THAT time. This presentation will describe what has changed since then and why is the answer to his question now a definitive: YES this technology is changing the technical documentation world and we need to be prepared.

Why ask the question again now?

Augmented reality (AR) has been in the field for more than 20 years. It has been promised a few times as the future of technical documentation, but has so far not fulfilled the promise.

There are more industrial applications that could benefit from AR, and consumer technology makes it available to all. So we should ask if AR is now mature enough, and what is missing to make it useful for technical documentation.

What is augmented reality (AR)?

Don’t mix it up with virtual reality. In virtual reality, everything is generated. Augmented reality combines the real world and generated content. For example, you could take a picture of a car and overlay it with an augmented image.

AR can include images, sounds, 3D data, 2D data – even marking up a book!


  • On TV, sports shows overlay game information on the picture.
  • The owner guide for a Samsung printer shows you how to change the ink tray.
  • Mobile: Live video overlaid on the screen, showing local information. Similar applications are available in cars, showing distance and speed.

What you need to build an AR application

These are the basics:

  • Sensors, to capture the real environment. A sensor can be a camera or a Kinect, for example.
  • A software application that overlays the additional information on the captured content.
  • Devices to display the augmented content. For example, Google Goggles, goggles and headset, projector, monitor, tablet, mobile phone.
  • Something that lets you interact, such as voice recognition, touch, gestures, wearable computers.
  • The AR content itself – a 3D model, the visual guidance (for example, telling the technical where to move his view), the voice overlay.


Juergen showed us two examples of AR in the real world. These videos are available on YouTube, as well as variations of them, such as from BMW. In the first, we saw a photo of machinery, with superimposed images of arrows telling you where to go, plus signposts naming various bits, and images of tools performing actions. In the second, we saw a technician repairing a car and wearing AR goggles that guided him through the steps where he needed help.

Deciding where AR can be useful

We can best use AR in situations where the repair is difficult or complex, and where we can guide the technician. We can show the technician where to carry out the repair, and we can align the AR with the current repair step.

We should make sure that we can give the technician just the information he needs, and eliminate the need for him to transfer instructions from screen or paper to the car.

We can also use the same material for training, either as training on demand or as formal training in a training centre.

The AR can supplement training with context-specific instructional information. We saw an example of a 3D wiring harness applied to a complex car. The technician can walk around the car and see the location of the various connection points.

Advantages of AR

  • It’s more efficient for the person accessing the content. (There’s more effort required in the creation of the content.)
  • The information adjusts to the current situation and recognises state.
  • We can reuse existing engineering data, such as a 3D model.
  • We can make use of existing consumer technology, such as smart phones and other mobile devices.
  • Various departments can make use of the AR solution. For example, repair, marketing, training, and so on.

What this means for technical authors

Content is essential for AR. The type of content changes, and so will the way we create it. We’ll need to build 3D overlay and voice overlay. We need to guide people to the correct location, and make sure the content is context sensitive.

We will need to use specific authoring tools where we work in a 3D view, and align the data with the real world. In addition, we will show people how to do a task, rather than explaining it. In effect, you are doing the task together with the technician.

What has changed since the question was first asked?

AR technology is significantly improved: better algorithms, more AR authoring tools, and more suppliers.

On the consumer side, we have mobile phones and tablets that can support AR, cheap 3D sensors like Kinect, Google Goggles, and voice control technology such as SIRI.

There are already AR applications in place: navigation systems that show you how to navigate, catalogues such as Ikea, search engines that can show you how to get to a restaurant, … and technical documentation.

Is AR the future of technical documentation?

Juergen thinks this is not a question any more. AR is already in use. People are using it in everyday life. So the answer is. “Yes, AR is the future of technical documentation.”

The task of technical communicators is to build knowledge and processes to support AR in the same sustainable way as we deliver any other technical documentation product.

The cosmopolitan information topic at Tekom tcworld 2012

I’m attending Tekom tcworld 2012, in Wiesbaden. Bright and early on the second day of the conference, Uwe Reißenweber and Waltraud Winter presented a session titled “The Cosmopolitan Information Topic”.

Here is the blurb for the session:

It’s time to stop thinking of customer documentation in terms of monolithic files, in all required languages, covering all legal requirements. Our customers are more than mere recipients of what we provide, lost in a world of words. Each customer needs appropriate content at the right time and in the right format, that is, topic-based information. For this reason, Siemens Healthcare has developed a new way of customer documentation, the Knowledge Gateway. This modern approach not only provides our customers with most suitable information, but also turns them into cherished collaborators. We therefore develop, maintain, and deliver topics of information as well as collaboration tools. The customers decide what to read, when to read it, and in which format to read it. And we stay in touch with the customers and learn from their experiences during the whole lifecycle of a product. In this way, a cosmopolitan information topic is the connecting link between the user and the information developers.

Uwe works at Docufy, which is the system underlying the Siemens documentation system. Waltraud manages a technical documentation team at Siemens, in the area of tomography equipment.

Waltraud started by telling us what Siemens wants to achieve with the new system. The system is still under development, not yet ready to be implemented.

Why a new approach to Siemens’s documentation system?

Doctors are using new technology in surgery. Even more, doctors have less time to spend on each patient. They don’t have time to waste reading the documentation.

The way people find information has changed. Waltraud showed images of Google, Twitter, Facebook, eBooks – we use different tools to communicate. We don’t look through thick books when looking for information.

The customer wants an instant answer to his question, and it must be the right answer. He wants to search for information.

Result: Siemens decided to deliver a portal to the customer, on the tomographical equipment. They will deliver printed documentation too, containing such things as safety information and FAQs.

They are designing a “Knowledge Gateway”, which is a portal consisting of 4 parts:

  • A web portal offering a flexible interface.
  • An up-to-date search engine.
  • Collaboration platforms that give the user in the hospital the chance to communicate with colleagues.
  • Publishing on demand, so that the user can print the results of his retrieval, or put it on his mobile device.

The search returns results, which are still in XML. The customer then selects the output format he wants, such as eBook format. This means that the customer can read the information when he wants to, and not when we say he must. That’s the big difference.

Topics are the basis for everything

To make this happen, they had to move from writing long documents into topic-based authoring. This is essential for the search, and is the basis of the new portal.

What is a topic?

  • Right size: A topic is something that should give the user the answer to his request for help (F1 click). That’s what determines the size of the topic.
  • Right metadata: This is essential for the search.


Search is very important. We need to make it as successful as possible.

You need facetted search results, via dynamic categorisation of search results. The search must be context sensitive, the result of analysis of a context and user model.

You also need a type-ahead search capability.


Based on the metadata, the system creates the links between topics. You need a metadata model that is sufficient to automatically create the relationship between topics.

Whenever someone uploads a topic to the portal, an automatic index process starts up. In addition, an automated process determines the metadata by analysing the context and relevance of the content. This is very important, as the technical writers do not have time to compile the metadata and relationships manually.


The customers can send feedback via the system. This helps the technical writers get closer to the customer, and the customer to get closer to them.

The technical side

The above  is what Siemens would like from the new system. Now Uwe took over, to tell us more about the technical side.

The challenge – linking topics to taxonomy

Technical writers must now write topics, and add the right metadata. But the authors do not know the ontologies, so adding the metadata is not easy.

Uwe said we need to turn the process around. Start by defining the classification, then add the topics required. Still, you quickly get to a point where it gets very very complicated. The structure is to build up a classification/ontology/taxonomy and link your topics into it.


How can the content management system support the user?

  • Strong topic management capabilities. There is no more concept of “document” except when the user prints the content.
  • Flexible classification features. You’ll need to extend the taxonomy constantly. It’s a moving target, and you must mirror it into the CMS.
  • Open and flexible interfaces. The interface must be comfortable for the users, and must integrate all systems that are related, such as translation.

It also needs to include other requirements of a CMS:

  • Versioning.
  • Traceability. This is significant when the user sees a dynamically-generated document, and you need to know which version(s) he saw at any one time, and which version he currently has on his mobile device.
  • Workflow.
  • Worldwide availability. Siemens is an international organisation.
  • Scalability and robustness. There is always someone working, due to the global aspect of Siemens.

Siemens has chosen COSIMA enterprise as their global CMS to fulfill the above requirements.


This was a fascinating topic, and hard to do justice to via these notes. The full complexity of the requirements came out in the Q&A session at the end, where we learned more about the users and the methods by which they will download the content onto their devices. Most users, for example, will be able to use a secure channel connected to Siemens. Others, in less connected areas of the world, will have to have this content updated by an engineer, via CD or other hard transfer devices.

Meaning in technical communication at Tekom tcworld 2012

I’m attending Tekom tcworld 2012, in Wiesbaden. This afternoon my friend Kai Weber is presenting a session called, intriguingly, “Addicted to Meaning: How Good Technical Communication is Like Bad Magic Tricks”. Here are my notes from the session.

Kai Weber writes a blog at Kai’s Tech Writing Blog. I’ve met him at a previous conference, and we’ve exchanged frequent comments on various blog posts. I’m really looking forward to this session!

Kai started by telling us what’s in this session:

  • What is meaning and why should we care
  • How does meaning work in communication and why does it still fail in tech comm?
  • How and why we create meaning and how to create meaningful documentation.

What is meaning?

The WKID pyramid:

  • Wisdom
  • Knowledge
  • Information
  • Data

Moving up from the bottom of the pyramid, you start from small bits of data and move up towards wisdom. We have a lot of data, but little wisdom.
Meaning starts at the information level. There’s much more on the knowledge level. Wisdom is meaningful too, but Kai says he’s not the expert there so we’ll focus on information and knowledge.

Meaning is meaningful and valuable because it allows us to connect the dots and see how something relates to our tasks. It answers the question, “why should I care and what do I do?”

Why should we care, as technical communicators?

What we do is to turn information into relevant and applicable knowledge.

As proof, see our principles and methods: know your audience, and write task-focused documentation.

How meaning works in communication

Kai showed us the Shannon and Weaver (1949) mathematical theory of communication. This is a great engineering model, useful for telephones, for example. But it doesn’t have much about meaning.

So Kai looked around and found the theory of semiotics (Fiske 1990). Communication happens when a listener interprets the signs (messages) from the speaker, based on shared conventions.

Technical communication tries to offer solutions for a number of the problems that semiotics have shown. Semiotics diagnoses problems, such as the fact that signs represent arbitrary stuff. Tech comm says that we should offer definitions and clarify with images and glossaries. Semiotics says that conventions/codes can include or exlude social or ethnic groups. Tech comm says let’s define standard language to ensure accessibility.

Why does it sometimes still not work?

We think our messages, conventions and media are clear. But for a large part of the time, we still misunderstand each other.

Von Foerster (1949) proposed the theory of radical constructivism: there is no meaning but the one created by the reader! He also said that each individual situation is a new beginning, another page one.

The reader ultimately decides what meaning he gets from the documentation.

How we create meaning

We combine our current situation with past experience. The way we do this is by matching mental models. These mental models shape what we think of the world, and how we try to solve problems.

Kai used the example of a restaurant. We all know how a restaurant works. We know how to look at a menu, order food, and solve problems such as when the wrong drink arrives. The model is fairly flexible – we can handle restaurants that are outside, or even self-service restaurants. We’re thrown if the restaurant is completely different, such as one in Japan.

Mental models are slow to change (like the Japanese one) and largely subconscious therefore uncontrollable. Windows 8 is so completely different from Windows 7 that people don’t know what to do.

In tech comm, we have an interesting problem because we are dealing with 2 mental models:

  • The mental model of the engineer/designer – which is inert and incontrollable.
  • The mental model of the user – which is also inert and incontrollable.

These two mental models meet in the system, and it is up to us to translate.

Why does it work some of the time? Because people are addicted to meaning.

Because we are addicted to meaning. People want to get their stuff done, and are really inquisitive about what things mean and how they work.

Examples: Google for “mondegreens” to see how we try to make sense of lyrics. Or see how we look at logos and try to make sense of them. Kai talked us through how we try to make sense of the coloured image of an apple, by Marcin Wichary.

People also seek order. We want to know how stuff hangs together, and how we can connect the dots.

What does it mean for meaningful user assistance?

It means this:

  • Our documentation must be relevant to the user and situation.
  • Or show us a workaround.
  • Or an explanation of why stuff is so weird.
  • Or at least give us some sympathy.

The most popular user assistance is help of a friend or colleage. That will give us all of the above four. Second most popular is Google.

Our documentation will offer the first two, but not the last two.

How can we create more meaningful UA?

  • Understand how people create meaning.
  • Adjust our content to the users’ mental models. See the techniques of user interface designers and user experience designers. Observe user behaviour. Offer several paths, for different tasks and personas. Be respectful of the way users have always done something. You do have to innovate, but be aware of the huge number of users who just want it to work the way it did before, just better.
  • Apply minimalism. Help readers to connect the dots, focus on process and outcome, not product. Give just enough information, and encourage them to develop skills. People are usually intelligent enough to connect the dots. For example, don’t tell people to “click Save” or “click OK” unless it’s really important. Encourage people to use the skills they already have.

Why is good documentation like bad magic tricks?

Good documentation doesn’t marvel you with fire and smoke, as did the wizard in the old film “Wizard of Oz”. It helps you by exposing the way the system works – it exposes the wizard behind the curtain.

Thanks Kai

This was a very interesting, amusing, and thought-provoking presentation. Meaningful. 🙂

Content strategy and mobile devices at Tekom tcworld 2012

I’m attending Tekom tcworld 2012, in Wiesbaden. Today is the first day of the conference, and I’ve decided to attend a number of sessions on content strategy.

Ann Rockley presented a session called “Supporting Multiple Mobile Devices with a Unified Content Strategy”. The blurb for this session is tantalising:

Smartphones, eBook readers, and tablets have forever changed the way people access and interact with your content. You need to be able to create content today that can adapt to the new devices of tomorrow. To do that you need to create a unified content strategy – a content strategy that takes into account the requirements of the customer, the content to be delivered, and the ever changing array of devices for delivery.  This session provides an understanding of:

  • A unified content strategy (UCS)
  • How to design adaptive content to support your unified content strategy
  • Structure
  • Business rules
  • Changing processes.

You really need a content strategy

Ann pointed out that you really need a content strategy, even if you’re only delivering small bits of information to a very small screen.

We looked at some stats, showing that the mobile market is growing rapidly. So is the share of market that browses the web via mobile devices. There are places in the world, such as Africa, that went directly to mobile, skipping the desktop phase. The growth of mobile is led by China and India.

What is mobile all about?

Designing for a small screen? No! Resizing visuals is not the solution to platform proliferation. The devices are all different sizes. We have a variety of different device types, which are in effect the new PC.

Moving from print to web

Things needed to change in the content. These aspects were different:

  • Page sizes
  • Resolution
  • Navigation and fining content
  • Understanding of depth and breadth of the information
  • And more

For mobile, we need to think about redesigning our content again.

But if you write well-structured, modular content, it works well online and on mobile devices. We’ve become sloppy and started designing content specifically for the web, instead of keeping it modular and structured.

Scanning versus reading

People move through information much faster. They don’t want all the information at once. We need to layer it.

Don’t design mobile-specific content

Ann says we shouldn’t design content for websites and for mobile apps. It is twice the work, or more. Instead, we should have a set of content that we push out in different formats.


This is another set of devices where we need to rethink our content. eBooks do not work the same way as help or print.

You can’t save a printed manual into an eBook format and hope it will work. It doesn’t. We need to think about how we can optimise the medium.

There is a large number of eBook platforms, making it difficult to test the content on all of them.

Move away from handcrafting

Devices are proliferating. It’s not sustainable to handcraft for each device. Anne showed us some statistics of the various mobile devices and e-readers available.

Anne pointed out that PDF files never worked really well, and now don’t work at all on small devices. It’s impossible to read a PDF document on a mobile device, she says.

How can we create content so that it will adapt?

Don’t talk about the devices first. Instead, talk about the content first. This way, you don’t care what the next device is. Design the content in a very modular and structured way.

The first step is to know your audience, the type of content they need, where they are, and we need some sense of the type of device they will use.

A unified content strategy

Ann has created a methodology for creating your information once, and delivering it many times.

  • An adaptive/responsive content model strategy. Design the models so that, depending on where the content appears, different models can be used.
  • A re-use strategy, so that the same content can be used in different types of manuals and devices.
  • Manage the content throughout the lifecycle – workflow.
  • Tag the content using a taxology.
  • Governance of the content.

Adaptive content

Adaptive content means that the information will automatically adjust, depending on where the information is displayed. It does more than just scaling the length of a line or size of image. It may also layer the information, via progressive disclosure. It’s more intelligent than responsive design.

It can also adapt to your future requirements.

Structure, re-use and modularisation

Ann now took us through the details of audience analysis, content re-use and structuring content in modules.

If you’re not producing structured content now, forget about going mobile. It’s not possible without structure. Examples of structure tools: DITA, DocBook, custom structuring.

Content modelling is essential, before you dive into a structured environment. Content modelling helps you to figure out how best to support your requirements.

  • Determine the current structure of your information.
  • Determine the proposed content structure.
  • Develop information product models and topic models.
  • Identify guidelines for structured writing, to go along with the models.

Important is to separate the content from the delivery of the content. You will be able to display structured content in different places, depending on the device, using style sheets.

Your re-use strategy affects the translation of content. For example, a small piece of content may be difficult to translate if it’s out of context.

Taxonomy and metadata

We need a semantic structure and metadata on our content, so that we can automate as much as possible. Think about a controlled vocabulary and a metadata tagging strategy.


We need to control the content as it moves through its lifecycle, and what the various people can do.

Business rules

Business rules will define how your content will react in different situations. Think, “if this happens, what should happen next”. We need to control these causes and effects, to ensure that our content adapts effectively.

In summary, Ann recommends that we work backwards from our customer requirements and device constraints, to design the adaptive content. Then we change our processes within the organisation, to support this design for intelligent content.

%d bloggers like this: