Blog

Why Users Can't Understand Your Content

How can we design technical information that users actually use and understand? At Tcworld 2017, information architect Jonatan Lundin shared the key insights he's gained researching this very question.

3 Common Tech Writer Headaches that Skribenta Solves

Working as a Skribenta consultant isn’t the simplest job in the world, but it is a lot of fun. Everyday, I discover new possibilities within the system that make life easier for technical writers. My role is to understand our customers’ challenges, then identify the most optimal solutions and customizations that both simplify the job of the tech writer and minimize all the boring manual work which often leads to human mistakes.

In my ten years working closely with tech writers, I’ve grown familiar with the kinds of challenges or “headaches” that often pop up, and equally familiar with how effectively Skribenta solves them. Here are a few examples…

Perfecting the Review Process: Chefs, Tech Writers, and Questions from the Test Kitchen

Many years ago, I heard my colleague (and founder of Excosoft) Jan Christian Herlitz say that reusable content is like food. Each reusable component is an ingredient in the kitchen, and with a recipe we can combine ingredients into a dish—a complete document.

Why Reading and Learning in Wikipedia is More Productive with Wikiview

When it comes to digesting information, one of the basic human tendencies is the utilization of abstractions. We learn it very early. It’s how, for instance, we’re able to identify the creature standing in front of us as a dog, when we’ve never even seen a Boxer before.

46 Questions that Will Help You Produce Better Technical Documentation

How We Built Excosoft: The Birth of a Company

The Spread of EXCO

EXCO’s usage spread quickly after Försvarets materielverk (FMV) adopted it into their operations in 1983. First at Ericsson Radio Systems (ERA) where I worked, then within other Ericsson companies — like Ericsson Radar Electronics (ERE) in Gothenburg, Ericsson Information Systems (EIS) in Kista, and Erisoft in Luleå. Next, EXCO spread to other large industrial companies, such as SAAB Military Aircraft in Linköping, ESAB in Laxå and ABB Automation in Västerås.

Soon enough, a technology consulting company called Frontec was requesting to become a distributor. It was through them that EXCO proceeded to spread to Alfa Laval in Tumba, and Atlas Copco in Lindingö.

How We Built Excosoft: The First Bubble 1986-1991

Small and Lucky

In September 1986 we were on our own. Some lucky circumstances helped us survive:

Ericsson Information Systems (EIS) was one of our customers and they were focused on the newly evolving PC market. We got an order from EIS to adapt EXCO for DOS— the Disk Operating System from Microsoft. We needed somewhere to be and they let us sit in a room, together with other consultants, in the big building very close to the Kista Center. After 6 months, we were ready. We got 80,000 Swedish Crowns for the job which was a lot of money.

One of our biggest customers, ABB Automation in Västerås, had been holding off on some orders until Excosoft was officially founded— these orders were now occupying most of Lennart’s time.

My father, 69 years and newly retired, asked me if I needed help with accounting. He had studied law and worked in the Department of Agriculture his whole life, though he claimed he had taken a course in Double Entry Bookkeeping.
I accepted his offer without knowing how extremely important his contribution would turn out to be. Keeping track of the financial transactions, paying taxes in due time, establishing bank relations and getting a credit check, paying salaries and invoices, and much more— all this just to function, to support the basic survival needs of the company. Meanwhile, we nerds focusing on programming didn’t have a clue! But my father, he solved the task splendidly. And he didn’t even charge us anything!

After the EIS job, we rented a little room from Radiosystem AB which had its own entry. It was located in the north of Kista. Now we started to feel like a real company. Pär joined the company. And then we hired Anette, realizing we needed a receptionist.

What is a Topic?

A “topic” can be defined in several different ways— a fact which often leads to inefficiencies in content management. Even if we can agree on the general function of a “topic,” the concept often remains confusing for many technical communicators. This is especially true in the context of a global content management team, with each individual technical communicator holding their own definition.

As technical communicators, our definition of a topic really depends on the form in which we make content available to our users. What follows is a presentation of what a topic means within the context of three different content delivery scenarios.

The purpose of this guide is to help you find clarity the next time you are discussing or communicating about topics. Hopefully this will help solve the problem that comes from having an unclear definition, and ultimately lead to greater team effectiveness.

Is it possible to create a web knowledge base from existing book manuals?

Check out our presentation from the largest conference on technical communication in the world- tcworld 2015 – to see how to create one (1) mobile-friendly web knowledge base from existing technical documentation books. This, without requiring any manual work to rewrite or re-structure the book content.

The presentation show how taxonomies are used to classify content in several book manuals, managed in the Excosoft Skribenta component content management system. These books are deployed to a responsive web knowledge base (generated by Skribenta Finder), where users use filters and relations to find answers.

Skribenta and The Debated Translation Unit

As providers of Skribenta, a CCMS with integrated translation memory, we sometimes receive inquiries from customers and translation agencies who are curious about the possibilities. There’s this one question in particular which we receive rather frequently:

Is it technically possible to output translation files segmented on the sentence level?

How Do You Define a User's Information Need?

As a technical communicator, you probably know why you design and write information. It’s because you want to satisfy the user’s information need. But how do you know what information users need in the first place?

Your answer will differ depending on how you define an “information need,” which is a central concept in the world of technical communication. The purpose of this article is to distinguish between two conflicting definitions of an information need, and to show how each perspective represented affects the design of end user assistance.

You should, of course, abide by the perspective that leads to happy users, but which is it?

The Flexibility You Didn't Know Existed in a Structured Documentation System

The fundamental idea behind structured documentation systems is that they allow their users to easily find and reuse documentation, and sync up with other systems. A common complaint, however, is that if changes are made to the underlying structure, everything and everybody is affected.

How Granular is Your CCMS?

Information re-use is a key feature of all advanced Component Content Management Systems (CCMS). Instead of copy-pasting text or authoring the same content over and over again, publications are built-up from little pieces of information that are created and maintained individually, allowing them to be re-used across multiple publications. Few voice dissent; it’s an efficient way of working, with cuts in authoring and translation costs as the main motivators.

How Can We Help Users Judge the Relevance of Content?

It’s not difficult for a user to find information—it’s as simple as opening a user manual or performing a Google search. What users often find difficult, is assessing whether the found information is relevant to their specific information need. A crucial component of end user assistance is, therefore, supporting the user in judging the relevance of what they find.

Are you a technical communicator working as an information architect to increase your content’s findability, with the goal of creating a happy user experience for your customers? Then this article is for you. Read on to find out how you can better support users in making accurate relevance judgments by designing your content for enhanced findability.

Put the Tech Doc on Management's Agenda

Something that’s really stuck out for me in my two years working with technical documentation is this enduring friction between technical documentation groups and business managers— they just don’t understand each other. While management chronically undervalues the very purpose of the tech doc, frustrated technical documentation groups are silently teeming with knowledge of it’s hidden potential.

Machine Translation– Friend or Foe?

Machine Translation (MT) is a major force to be reckoned with in the field of technical communication today. Whereas the human translator works for a salary and at their own steady pace, Machine Translation gets the job done for next to nothing and with unprecedented expediency. It’s no wonder so many are looking to Machine Translation to cut costs. However, despite such savings there exists a trade off when it comes to the quality of the end product. For documentation departments, or other purchasers of technical translations, some insight into Machine Translation may be valuable. What follows is a simple primer on the basics.

How We Built Excosoft: The Importance of Keys

It’s worth taking a moment to pay tribute to the tools of the time, when EXCO was first coming into being. EXCO was developed in the context of a key-centric, terminal-based computer era— a stark contrast to today’s mouse pointing, screen-touching navigational approach. Let me paint a picture of what working on computers was like in those days.

Can Tech Writers Create Links without Even Writing Them?

This article discusses why links are important, and how technical communicators can make them without actually explicitly writing them.

Some technical communicators say that links should be handled with care, especially in a topic-based environment, since you can end up with broken links depending on how you organize and filter topics. Also often discussed, is whether links should be embedded or inserted at the end of a topic as a list of references. The technical communication community has at least come to the agreement that creating a link strategy, and the actual links, is a time consuming affair.

3 Things All Tech Writers Struggle With

Being in the technical documentation business, we naturally maintain close contact with the inner world of technical documentation and the users of our product—the tech writers themselves. In the interest of being able to offer the best product possible, it’s our job to understand the everyday life of tech writers: How they work, what they're aiming to achieve, as well as what challenges they encounter most.

Could Forming an Office Music Band Optimize Teamwork?

I’ve recently made a curious discovery about my fellow co-workers. Whether it's a lunchtime break or the rare after-work, for some reason our conversation tends to gravitate toward the subject of music. One employee will say, “I used to be an opera singer.” Another will volunteer, “I play the guitar.” Me? I play the oboe. Even the CEO is in on this peculiar pattern, we eventually find out, with his lifelong devotion to playing the piano.

Why Should Technical Communicators Avoid Target Group Analysis?

Us technical communicators have been taught that end user assistance for a product should mostly include instructions addressing specific user tasks. But how do you know that the method you’reusing to identify these tasks, such as Target Group Analysis, actually leads to the information users are searching for?

I have always thought that grouping users into target groups, like installer, operator, etc., and analyzing the tasks each group is supposed to perform, is the wrong starting point for anticipating the information needs of users. Especially when designing information intended to support a user of your company's products.

6 Reasons Your Marketing and Tech Doc Departments Should Be Thinking Together

Many product-based companies view technical documentation as an isolated instance that has little to do with the rest of their communication-related operations, like marketing. This often overlooked disparity cannot fare well, however, in today’s information age, where everything you write or take a picture of ultimately ends up on the internet— whether it’s you who’s put it out there, or your customers themselves.

How We Built Excosoft: The Early Adopters

EXCO for Programmers

Back at Ericsson Radio, following my 1980 summer holiday, I presented EXCO Editor to my colleagues. It was very well received and programmers started to write hierarchical code.

This technique later became known as Literate Programming. In Literate Programming, the real code is wrapped inside pseudo-code, i.e. descriptive titles which document the code. Pseudo-code can be wrapped in higher levels of pseudo-code, thus creating higher levels of abstraction.

Managing Variation in Reused Content with Configuration and Automation

It’s time to wrap up this series on Managing Variation in Reused Content. We have investigated some basic techniques in part 1 and part 2. In part 3, I made the case that heavily customized documentation is often best handled in separate version branches. Before concluding, let’s take a quick look at two advanced topics: configuration, and automation.

Why is it Important to Design for the Searching User?

In the Designing for the Searching User series I discuss how to predict user questions, and how to make answers findable. But equally important, is to discuss why we are doing this in the first place, and what it actually means. This edition to the series is devoted to addressing these questions, and to supplying technical communicators with some solid arguments for why now is the time to change our approach to user experience design.

4 Tips for Translation-Friendly Tech Writing

As a fairly new member of the Excosoft team, I’m honoured to add a few words to our blogosphere. My background isn’t foremost in engineering, but rather in linguistics, translation, and technical writing—so I'll be contributing on those topics.

A CCMS for the Content Providers

Technical specialists are the content providers in the world of technical documentation. Whereas technical writers take on the role of editing product information for optimal user comprehension, the content providers are the inventors, product owners, and technical specialists standing closest to the product itself. They possess in-depth knowledge of how a given product works, why it exists, and what solutions it has to offer its users.

How We Built Excosoft: The Dawn of the EXCO Editor

An Electronic Engineer Turned Programmer

In 1975, Stansaab, a company outside of Stockholm, got a big order from the Soviet Union: 3 air traffic control systems for Moscow, Kiev, and Mineralnye Vody. USSR wanted to be prepared for the increased air traffic expected in 1980, the year of the Olympic games in Moscow.

Managing Variation in Reused Content with Version Control

In part 1 and part 2 of the Managing Variation in Reused Content series, we covered two basic techniques: Injection, and Conditions. Injection is a method where values, or small pieces of text— often names or measurements— are extracted from topics, and stored as variables. When the topics are to be published, the values are loaded from the appropriate variables and injected into the correct place in the text. Conditions function as filters, sifting through parts of a topic, and adapting it to a given context.

Is Intelligent Content a Good Idea in Technical Communication?

Over the summer, I became a bit provoked while reading the thoughts and opinions of people in our industry regarding how technical communication is supposed to look in future. My overall impression left me mulling over the following question: Should technical communicators be designing content so that the right information presents itself to the right person, at the right time, on the right device, and in the right location?

Next Revolution is Information Handling

I came from the mobile telecom industry. In only a few years we literally changed the world. The next revolution is clearly that of information. In the midst of what’s become a truly globalized world, it’s vital not to drown in the tsunami of information that’s come with it. Not least, you should try to avoid drowning when it comes to producing information or content in a multitude of languages, formats, versions, and brands.

How Do We Know Which User Tasks to Write in Manuals?

Many technical communicators have learned that an end user manual should consist mainly of tasks. That is, instructions detailing each step that users are recommended to follow. And indeed, a user must complete many tasks do get a product to work.

But how do we know which tasks to write about in end user manuals? Are you like me, a technical communicator who finds it confusing at times to identify what task to write? Then this article, part 6 in the Designing for the Searching User series, is for you.

Create a Manual in 10 Minutes

Every time I meet a customer who is considering setting up a CCMS, there’s this thick air of reluctance in the room. They envision a mountain of work ahead of them, with ultimate benefits taking years to fully realize. As a sales guy, I try to keep the focus on the ease and time-savings that await them once the new structure is in place. Plus I’m honest— while implementation doesn’t require a year long process, neither can it be accomplished in 5 minutes. However, once set up is complete, the benefits can be enjoyed immediately. How do I prove the point? From my experience, nothing speaks louder than a real-life example.

Managing Variation in Reused Content with Conditions

In part 1 of the Managing Variation in Reused Content series we investigated the basic technique of Injection, in which interchangeable names are extracted from topics and stored as variables, which are then injected back into a given topic when it is published. Injection is extremely effective in some situations, but many content variations are more complex and require a different approach. A more versatile technique is the use of conditions.

What Types of Questions Do Users Ask?

A core skill required of technical communicators is the ability to determine what type of information end users need in order to achieve a particular purpose. Many technical communicators, including myself, struggle at times with figuring out what information to write and how to organize it. See for example a recent discussion on LinkedIn.

In my previous article , I discussed the principle of predicting user questions and introduced the concept of question type, which serves as a fundament to knowing what type of information to write. But what types of questions do users ask?

Tech Doc Automation Next Step in LEAN Revolution

LEAN is the name of the game these days, especially in the realm of industrial manufacturing. With an increasing number of competitors in the global playing field plus a considerable upsurge of information flow, streamlining the production process is vital to maximizing value and staying in the lead.

Much has already been done in terms of automation to achieve alignment with the principles of LEAN manufacturing. Yet, there remains a lesser-explored opportunity that can make a considerable difference– namely, the automation of technical documentation.

Managing Variation in Reused Content with Injection

For technical communicators, the concept of reusing content is easy to understand. Chunk the content up into smaller, self-sufficient units that can be used independently of context, then combine the units as needed to assemble different documents. This is the fundamental idea behind topic-based authoring. One question that often comes up is, how small or large should the chunks be? This can be approached from two different angles: by considering either what is relevant for the reader, or what is practical for the writer. Ideally we should only consider the needs of the reader, but is that really possible? It depends upon the answer to another question: how is variation managed in reused content?

How Do We Predict User Questions?

Many technical communicators struggle to define what type of information should be put into different types of manuals, and how it should be organized. At the same time, they’re faced with pressure to escape the book paradigm; the traditional book-like manual that is leaving customers frustrated in their inefficient pursuit of information.

The Catch-22 and the Super Manuals that Saved the Day

Metso Minerals and their technical documentation department were snagged in a catch-22. The renaissance of the mining industry had presented them with a great opportunity to thrive and expand, yet a time consuming technical documentation process was threatening their competitiveness in the marketplace.

Turning the Tables: Putting Technical Communicators in the Driver's Seat

The role of technical communicators may be about to change. Corporations are increasingly making use of the knowledge production capabilities built up within their technical documentation teams to drive business processes, and create value beyond the documentation itself.

How Do We Make Short Answers Easy to Find?

Current ways of delivering technical documentation-- such as via a PDF or CHM file, HTML web help, or Wiki, etc., all have something in common: content is organized in a static, arbitrary structure. In such a book-like format, the table of contents is often the user's only option when it comes to finding relevant information. It's an almost impossible challenge to design a static structure that everyone finds logical.

Do You Have a Get-Online Strategy for Your Tech Doc?

All companies want to be on-time to the market. Just listen to the commentary being exchanged in the corridor, like “We must launch this in an APP”,or, “I saw that in company X’s new series they can control their system from a tablet… why can’t we?”

Why not be among the first with an online solution? Upgrading your technical documentation is an easy first step, and can act as a seed of expansion; leading to seamless integration with other critical business systems, and resulting in a truly holistic online solution for both you and your customers.

Raising the Standards for Simplified XML Editing

What would happen to Microsoft Word if its users were required to not only make sense of the complicated XML1 markup which is used to store files in the docx format, but also to put up with error messages proclaiming things like “myprojectplan.docx:67:20:E: document type does not allow element ‘p’ here?” The program would probably be a lot less popular to say the least, and most people would seek alternatives. Yet, technical communicators using XML-based editing tools are expected to put up with that sort of thing all the time— all in the interest of a higher purpose, such as quality improvement and slashed translation costs. But it doesn’t have to be like that.

Should the Answer to a User Question be a Short or a Long Topic?

A user asks questions when stuck in product use. Displaying information-seeking behavior, they search for answers; and it’s you—the technical communicator—who is responsible for providing them with one. But then you get stuck as you ask yourself: how long should the answer be? As the question of topic size, (as in a DITA topic), continues to be controversial in the technical communication community, we also need to ask ourselves how the size of an answer relates to the size of a topic. My conclusion is that users prefer short answers. Why is this? And how do we make short answers findable? This post, part two in the article series Designing for the Searching User, provides insight into how to design next generation technical communication.

Upgrade Your Unfriendly User Manual and Tune-In with Your Customers

You've spent a lot of time and resources developing a comprehensive user manual, catering to every thinkable question a user might have about your product. So why—why, you may ask, are my customers calling my support department again and again, seeking answers to simple questions that have already been addressed?

The NS Loop: A Story of Rediscovery

When I joined Excosoft in 2006, no one had told me about the NS Loop function. It had kind of been forgotten at Excosoft, or at least buried at the bottom of the toolbox. I happen to have a passion for reuse, and enjoy scouring the archives of technical documentation for those lesser known tools which can be reapplied to new challenges. The NS Loop was one of those rediscovered tools, and this is what I learned about it: