Improving the effectiveness of information

In the previous episodes of this blog about writing effective articles, we have looked at two things: Defining your goal Defining your target audience Now that we have a clear vision of our goal and know for who we are writing this article, the next step is to create a conceptual model of the article. It is like creating the blueprint for your new home: starting as a sketch and in a number of increments it gets more and more detailed until you have reached the point that you can start decorating the house. Creating the overall plan for your article During my study in Linguistic competence, I learned to represent the structure of my text in an hierarchy. While this may work for informative articles, this is in my opinion not the best approach for goal-driven articles. For a goal-driven article the overall structure should in my opinion look like a process: a serial structure of steps leading towards a conclusion.  In this first rough sketch of your article, you start to defi...

Sometimes you need to fall back on the oldest technologies available to get the most out of the latest and greatest. This is also true when developing smart documentation. My current project involves the creation of a smart documentation solution for the Be Informed Business Process Platform (BPP). The documentation solution is targeted at users with various educations levels, different skills and experiences and with various roles in an organization or project. And to make things even more complex: the total set of documentation should at least cover all current versions of the BPP, the business solutions that are used on top of it and the implementation and project management methods used during implementation. Preparation  As mentioned in my white paper about creating smart documentation, the preparation for a smart documentation project - before writing the content - consists of the following steps: Define the goal, audience, and context: Clearly define the context, g...

At the STC Summit 2013 in Atlanta, I demonstrated how we can create smart documentation by using semantic technology. The session was well visited and there were a lot of good questions. During the session I modeled live - together with the audience - on a smart maintenance manual for oil tanks. To me - being from a country where we don't know or use these kind of tanks next to our houses - this felt like the ultimate example, completely relying on the expertise of my audience. The demo The starting point was a very basic procedure, consisting of four main activities: In the first step we determine the situation. We start with a short situation description and then - instead of describing what possible situations there are and linking to the pages - we ask our users about their situation. As it is not relevant for people that don't own an oil tank yet to read the maintenance instructions, the first question we ask is whether or not the reader actually owns an oil tan...

There is no doubt that the introduction of semantic technology in documentation, will change the way we create our documentation. Increased product and brand engagement Figure 1. Happier users Smarter documentation will lead to happier users, who reach their goals faster and with less frustration. Documentation that exactly responds to individuals will enhance perception of the product and the brand. Although positive feedback travels less quickly on the social media than negative feedback, it will not only impact the product and brand engagement of current customers but also motivate potential customers to take a serious look at your product. It will also influence your image and reputation as a technical communicator in the market and the value you offer to your contractors or managers. In this perspective technical communication will become a profit center instead of a cost center.   Increased documentation engagement Figure 2. Continuity of work Lookin...

A knowledge-based, semantically-modeled process can provide exactly the right result for end users and a powerfully effective tool for working teams in an organization. An additional benefit comes with the semantic solution for documentation: the ability to generate multiple output forms in multiple languages and addressed to different audiences from one set of models and content. User manuals, reference documentation, contextual help, in-context explanations, on-line user-assistance and complete inter- and intranet sites can be generated from one single repository, consisting of the relevant models and references to the content. Generating multiple documentation forms is one step in the process of providing documentation as a service. We can take it even one step further by integrating all these output forms in one smart user assistant. The smart user assistant adapts to events, answers questions, gives advice and assists in completing tasks. The key is computing with knowledge in t...

The use of models fits perfectly in the professional approach of creating user documentation: Define the goal, audience, and context: Clearly define the context, goals, and audiences. The design of documentation should be goal-driven—from the user’s point of view. Often, a brown paper or moderation session will help you define these goals and requirements. Involving users in this first step helps them understand the process and gives them an ownership stake in the solution. Create models of the goals, models and other important context factors and discuss them with the involved users. Analyze processes and activities: This is an important step in creating goal-driven documentation and should lead to a model of all relevant processes and activities. Also define the roles of different users within the processes.   Create the overall documentation model: this phase involves creating an overall structure for the product information, as well as linking this product model to the pr...

Reaching a smarter form of documentation requires that we start to develop other strategies for displaying knowledge even as we change how we gather and store it. Among the solutions we can offer to accomplish this smarter form of documentation are combinations of non-hierarchical navigation, faceted navigation, decision trees, wizards, and faceted search. But first we have to break our habit of hierarchical structuring all our content in chapters, sections, and subsections. Many web sites, manuals and help systems share this structure: all content elements are sub-themes of an element on the preceding level. Figure 1. Many web sites, manuals and help systems are build up like a book with chapters, paragraphs and sub-paragraphs A hierarchical, structured approach is optimized for the most informed users: the developers and designers who created the product. The path it indicates would be the most direct route to becoming an expert user of the product. But for users who need to ...

In my previous posts I have focused on the benefits of semantic technology in documentation for end users. Semantic technology also offers a great opportunity to support the documentation creation and revision process. Semantic technology replaces a disconnected, post-hoc documentation routine with a dynamic process that is easily deployed, tested, reviewed and revised. Every relevant stakeholder can be involved in the documentation process, as users and as authors. Smart documentation builds internal engagement for the organization in the same ways that it builds external engagement in the customer base. The modular re-use and incremental revision of documentation will reduce total cost of documentation. Support all parties in the product life cycle Using semantic technology in documentation makes it possible to optimize Product Life Cycle Management: It can support all documentation processes for all parties in the product life cycle. It also enables the re-use of information an...

Digital technology has allowed the documentation process to evolve from single document-centric to single source-centric: From creating individual manuals to creating re-usable chunks of information for a series of product and document types through various channels. Figure 1. Documentation evolved from document centric to single source centric Example A manufacturer of agricultural machines needed a complete line of documentation for its new type of harvester. In a document-centric approach, this would mean having one technical writer create the user documentation, another writer create the service manual and a third create the on-line help. In the best case they would copy chapters or paragraphs from one manual to the other. All of these documentation types would need to be reviewed by hand and individually updated when the harvester’s features changed, or new rules for its safe operation were implemented. In a single source environment, multiple writers work on discrete top...

As announced on several social media, I will demonstrate how we can use semantic technology to create process-driven documentation at the STC Summit 2013 in Atlanta.  I will do this by live modeling with a semantic tool set. Now I could do this with a predefined demo set, but what's the fun of that? So I would like to invite you to send a delimited instruction - this could be a chapter from one of your manuals - by uploading it to our server. From the uploaded manuals, I will select one or more to be modeled out.  As the models in the semantic environment are instantly executable, we can watch the documentation develop, change the models and review the results in a web browser. Wouldn't it be cool to see your documentation modeled out on the large screen at the STC Summit? When: May 6th, 2:00 pm (EDT) Where:   Hanover FG, Hyatt Regency Atlanta - Track my session Level: Advanced Uploading your file   Go to http://info.beinformed.com/stc13-upload a...

Instruction manuals, users guides, and other types of documentation have always been the way manufacturers distributed the how-to information about their products to customers, as well as sales and support staff and other employees. This kind of catch-all, one-size document forces every user to sift through irrelevant information, applying their own context to find solutions to their problems. Even when they are successful, users remember the experience as painful and tedious. What if you could take each individual user by the hand and guide them through the product, showing only what is relevant in their situation, immediately answering their questions and helping them make decisions and choices? Seamlessly effective, customized support would improve the user’s experience of the product and help them to feel engaged by the product and its brand. Product and brand engagement Product and brand engagement is – a partly emotional, partly rational – process of forming an attachment...

When I introduced my topic "Using semantic technology to create process-driven documentation" in the technical communicators group, I received some feedback referring to semantic tagging. While semantic technology offers us great possibilities to make our information accessible, it can easily lead to maintenance problems when not handled in the proper way. Using RDF, RDF Schema, XML or other specialized meta-data languages, it is – for someone who knows and understands these languages - relatively easy to set up a system that can lead to the desired situation. And as long as the meta-data is used in a consistent way, everything seems to work out fine. But as departments and teams change, the repository of used taxonomies and tags may become unavailable. When the organization rolls out new products, or changes its mission, new content may render today’s schema a relic. Example: eRDF mark-up for a decision about an upgrade Using any form of code or specialized me...

In the previous post I mentioned that creating user-oriented documentation requires an understanding of the audience and its tasks and processes. The trick has always been that it is hard to explain the days or weeks spend on audience and task analysis, while it doesn't deliver a visible contribution to our work from the start. There also isn't a real method or framework - that we can refer to - that demands the activities and deliverables that come with an audience and task analysis. In this a rea we can learn from ICT Architects , especially when it comes to: Usage of a common and widely accepted framework like DYA or TOGAF Development of standard notation methods, like Archimate for creating models of the different architectural layers of a solution Visibility of all activities and models in the end result. Standards versus an Open Framework A fact is that there are standards for documentation, but they are more or less focused on the quality of the end product and not on t...

In my last blog I explained how we can distinguish three phases in the development of documentation. The first phase was a very product centric one, while in the second phase we see a more process driven approach. Re-use gets more and more important as is collaboration with other writers. But what about the users? How do they benefit from this move to single sourcing? Sure, creating and translating documentation becomes cheaper and easier to manage, but having documentation in your own language is for most people normal and not seen as a usability feature. And then there is the issue with information overload. Maybe we should ask our users what information they need, instead of just providing them with everything we want them to know. To really help our users, we should move on from our process centric approach to a more customer-centric one. A customer-centric approach Documentation 3.0 is all about offering the right documentation at the right time. It is customer-centric, which mea...

The trends in documentation of the past 20 years are under heavy influence of the development of internet technology. Like with the web – where we distinguish between Web 1.0, Web 2.0 and 3.0 - we can see three phases in documentation. I will call them Documentation 1.0, Documentation 2.0 and 3.0. Where Documentation 1.0 is - like Web 1.0 - very much centered on individual products and information, brings Documentation 2.0 a process-driven approach with a focus on re-use. The customer-driven approach of Documentation 3.0 is a logical next step. But why should we change the way we create documentation? First of all the world is changing and so are our users! Things that seem obvious to one individual, don't make any sense to others. Take for instance this photo (shown to the left). It shows a young model holding a camera. In her perception, you hold a compact camera this way. Truth is that she is holding a 1970's Olympus Pen EE-3, a camera with a viewfinder instead of a LCD scr...

The March edition of the Intercom features my article about using knowledge technology for more effective intranet sites as the cover article. In this article - "The Flexible Intranet" - I examined the typical problems found in a corporate intranet site and demonstrated how knowledge-driven design can improve the effectiveness of intranet sites. In the article I used the example of a helpdesk that delivers support for mobile phones. With this example I demonstrated how an effective intranet site guides the helpdesk employee toward the information and presents the answers to the questions they are confronted with. Intercom, the magazine of the Society for Technical Communication , is published to provide examples and applications of technical communication that will promote its readers' professional development. Intercom is published for the benefit of STC members, each of whom receives a subscription to the magazine. Subscriptions are not available for non-members.

I mentioned in my last article of 2007, that as a technical writer you can expect to be asked for several kinds of documentation within your organization. Recently I started to structure the product requirements and product specifications of my customer's products. The intended audience consists of the product manager and product architects on the one hand and the developers on the other hand. The goal of my work is to create a knowledge bank in which the audience can see both the product requirements and the relevant specifications next to each other. At this moment there are two types of documents: A functional requirements document: This is a 27 pages long Word document, including some illustrations. It has a thematical structure. This document is written and edited by two product architects. Component design documents: These are detailed functional and technical descriptions of parts of the product, first written by developers and then edited by two functional designers. The co...