46 Questions that Will Help You Produce Better Technical DocumentationRead More
Information Design Tech Writer Tips
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?Read More
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.Read More
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.Read More
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.Read More
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’re using 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.Read More
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.Read More
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.Read More
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.Read More
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.Read More
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.Read More
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.Read More
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?Read More
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?Read More
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.Read More
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.Read More
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.Read More
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.Read More
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:Read More