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...

In my previous article, I described how I used a Card Method to gather input from my audience for a Smart Documentation solution. My approach for these sessions was: I prepared approximately 20 cards with topics from the current version of the system I invited 18 respondents for a 30 minutes session The sessions consisted of three parts: To start with, I asked every respondent to make five cards for the five topics that they would like to find on the new system. By narrowing it down to five, I encourage them to only write down the most important topics. At the end of this step I asked them to make categories of these five cards, each category forming a column on the table. In the next step I - one by one - gave them the prepared topics and asked the respondent to add them to an existing category or create a new category for it. When all cards were done, we reviewed the categories and made final adjustments In the final step, the respondent wrote down the labels for the categor...

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...

In the previous posts I have talked about the advantages of having a widely accepted framework for technical communication, just like ICT Architects have. This Technical Communication Framework (TECOF) could be our equivalent for TOGAF. The similarities between Technical Writing and ICT Architecture don't stop at the overview level, we can also learn from the model-driven approach from ICT Architects towards the detail levels of a solution and its context. One of the areas where we can benefit from this approach would in my opinion be the audience and tasks analysis, at the start of a technical communication project. A structured approach to audience and task analysis Archimate is an 'architectural language'. It provides ICT Architects with a vendor-independent set of concepts, including a graphical representation, that helps to create a consistent, integrated model which can be used in for instance TOGAF's views. The business layer in Archimate neatly corresponds...

In this third episode of my series about lessons learned as an ICT Architect, I will explore the possibilities of reusing the general ideas behind the TOGAF framework as a starting point for a technical communicators framework. ICT Architects use frameworks like TOGAF as a detailed method and set of tools for developing an enterprise architecture. Every component in this method delivers a visible addition to the end product. TOGAF 9 Components The TOGAF 9 framework for Enterprise Architecture consists of 8 components : Architecture Vision: this describes in scenarios how the new solution or application will meet the business goals and strategic objectives and address the stakeholder concerns when implemented. Business Architecture: models that describe how the high-level business requirements (from the Architecture Vision) can be mapped to actors, roles, business functions, business processes and services. Information and Application Architecture: this focusses on identifying ...

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...

Just like technical writers, ICT Architects face the challenge to describe platforms, systems and solutions from a business point of view. But where there seems to lack a standard for technical writers, ICT Architects have the luxury of having frameworks like TOGAF and notation methods like Archimate to help them do their work. Function-oriented versus user-oriented documentation No doubt that there are still technical writers out there who don't agree with me, but to me it is clear that a user-oriented approach to documentation is the way to go. So if I am talking about making documentation from a business point of view, I am in fact talking about creating a documentation solution that fits the user's needs. Whether or not this is a printed book, a website, embedded on-line help or a combination of all these, doesn't make a difference, as long as the presentation form is chosen from a user's point of view. Where to start? We all know the feeling when we accept a new pr...

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. Product centric documentation The first phase is the phase in which we technical communicators worked with tools like Pagemaker, QuarkXPress or Framemaker. In this phase we are very much focussed on a single product and there is a constant struggle between task and function based documentation. If our customer needs a manual for a product, we write one – as an isolated process. Our focus is on the product and generic audience groups and not on things like re-use or efficient use of available information. Compare it to the story of the little prince, where the author makes three drawings of a sheep – each sheep could be a version of a product; with us technical communicators writing a separate manual for every version. Sure we see the similarities and do ...

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.

When creating the models for a Knowledge Solution for an organization, the first two steps are: Making an overall model of the information goals, audiences, types and sources within the organization and look for possible similarities Defining the rules for the models that you are about to create. Making the overall model As mentioned before, my task was to design and create a knowledge bank in which the product architects and developers could easily find and compare product requirements and relevant specifications. This little project was part of the overall project that I am working on: creating a series of knowledge banks for my customer, covering all aspects of the product life cycle. I had already finished the (initial release of the) product documentation, so it was a logical step to design this particular knowledge bank in a way that it could benefit from the models and descriptions from the product documentation. All knowledge models - the ones already created and the ones plann...

A couple of weeks ago I started really enthusiastic with structuring the product requirements and product specifications of my customer's products. The goal of my work was to create a knowledge bank in which the audience can see both the product requirements and the relevant specifications next to each other. Last week I have finished the knowledge bank and presented it to the product architects. What did I learn from this project? Don't use your documentation project to restructure the whole organization First of all: it is impossible to capture the whole world in just one set of models. When you have to think of a documentation solution for a whole organization, it is tempting to restructure everything into one consistent overall structure. The truth is that in an ideal world this would be an excellent solution. In the real world you can't just change everything to get the desired result. Make a series of models for every single department or organizational unit that has ...

In the previous entry, I demonstrated three types of knowledge models. These models can help us structure the information we acquire from functional specifications, subject matter experts, the marketing department and - in some cases - our own observations. When combined they offer us different paths to our information. We have looked at: Thematical models Taxonomies / concept models Composition models A fourth model is called the Attribute model . An attribute model shows attributes and values: colors, specific characteristics, etc. An example is shown below: With the attribute model we can describe all possible characteristics of a product range and link them to the actual products. This makes it possible to make an overview of all variations within a productrange. The models can help us choose between products. Example: You call the service desk of the manufacturer of your TFT screen Service desk employee: "Do you know the exact product type?" You: "I am not sure, I c...

Last time, we have discussed what the benefits of knowledge modelling are. Now it is time, to take a first look at knowledge modelling, starting with a simple hierarchical model: As technical writers we are used to work with these kind of content structures, as illustrated above. This is the type of structure we not only use in manuals, but also in most on-line help systems and even websites. In this example we see two levels of information. When we would put this content structure in a graphical model it would look like this: All content elements - we call them 'concepts' in a knowledge model - are related to the next level with a relation of the type 'Subtheme of'. This type of knowledge model is very suitable for navigating and is supported by a large group of documentation, Help and website tools. Another very common knowledge model is the taxonomy. This type of knowledge model shows classes of concepts and their sub-types. All relationships in the model are of the ...

In my article in ISTC's Communicator (Autumn 2007) I explained that developing more effective information products asks for a knowledge-driven approach to communication. This knowledge-driven approach requires first of all that we offer the knowledge needed in a usable and understandable way, in line with the user’s knowledge and level of experience. The second requirement is that we should offer our users the right knowledge - from the enormous amount of available knowledge – at the right time. New semantic technology provides us with the opportunity to support our users in interpreting information within their context. The most important characteristics of these solutions are: non-hierarchical navigation: presents a mind map of the information, with different types of links making it possible to browse quickly through related topics and offering different points of view to different types of users decision trees: help users to make complex decisions by asking them simple question...

Be Informed offers a solution for publishing the same information — witt one model set and multiple content sources — to different media, in different formats and for several audiences. One of the disadvantages of the toolset - for international audiences - was that untill now all Be Informed releases were targeted at a Dutch user group, only containing on-line help and user assistance in Dutch. Be Informed hired me to produce a new on-line help system for their product suite, featuring both English and Dutch documentation. With release 3.2.4 the first version of this on-line help - with both function related help and some task related guidance - will be available. The upcoming months a configuration wizard and step by step guidances will be added to the documentation. The international release of Be Informed is scheduled to be launched on the 10th of December 2007. The on-line help will also be released on a website. I will come back to this as soon as it is available and provide you ...

The Machinery Directive(MD) sets out safety requirements for new machines, assemblies of machines, interchangeable equipment and safety components, which must be met before these products can be traded within the European Economic Area. As of the 29th December 2009 the provisions of the new Machine Directive (2006/42/EC) will be applicable. This new Machine Directive includes some modifications to the essential health and safety requirements. An important aspect within the Machine Directive is the product documentation. Within the new Machine Directive the traceability of documentation becomes more important than ever. Manufacturers must keep the EC declaration of conformity and declaration of incorporation for a period of at least 10 years from the last date of manufacture. The focus will be on the whole lifecycle of products and its documentation, with special emphasis on operational health and safety issues. Documentation specialists now face the challenge of creating documentatio...

Yesterday I received the author's proof of my article "How knowledge becomes usable", scheduled for publication in the Winter edition of Communicator, the quarterly journal of the Institute of Scientific and Technical Communicators (ISTC). This article is a follow-up on my presentation at the ISTC Conference 2007 in Liverpool, where I explained how you can incorporate knowledge-driven design in information products. The Winter edition of Communicator will be published in December 2007. If you are a member or a subscriber of Communicator, you will received this issue when it is published. Otherwise, if there is something of interest to you, contact the ISTC Office to purchase a copy. The ISTC is the largest UK-based society for professional communicators. If you are a technical communicator and working in the UK - or Europe in general - I can strongly recommend membership of the ISTC. Look for more information on their website: www.istc.org.uk .

In my profession as a technical communicator, there is a huge emphasis on creating information: every new product and every law, policy, rule or process has its own documentation. And, although content management systems help us reuse existing information, the total amount of information is constantly growing. Finding the right information within a reasonable amount of time is becoming more and more challenging for users. Search instruments and navigation trees do not offer a proper solution. As users of search engines like Google and Yahoo now, even the most sophisticated search engines cannot determine what information is relevant to the user and offer long lists of possibilities. On top of this, novice users often lack the necessary information to phrase useful inquiries (Horton, 1994). Navigation trees work fine on small-scale websites but, as soon as the number of topics grows, both the width and the depth of the navigation tree grow tremendously. New semantic technologies enable ...