Improving the effectiveness of information

As a writer I am always eager to get my articles published. Unfortunately – like with all processes – speeding up things often has a negative effect on the end quality of your product. Taking the time for a serious QA step, pays of in a more effective article. There are two processes that you can use to improve the quality of your article: Review process Pre-test process In an ideal situation you do them both. Get reviewed Although most of us are excellent writers, capable of delivering the message to an audience, it is always a good idea to set up a review process for your article before you post it on your blog or send it in to a magazine. A review process in an ideal world consists of two activities: A peer review by someone who knows the topic: technology, method or issue; A grammar & style review by a trained editor. For the peer review it is important to always provide the goal and audience definition to the reviewers, so they know what you are a...

In the previous blog posts, we have talked about the criteria for effective articles and how important it is to set a goal before you start. Now suppose you have decided to write an article about new technology that enables organizations to perform better and make more profit. The goal of your article is to persuade the reader to come to one of the conferences where your company demonstrates this new technology. Would you be interested to hear what your neighbor – a software engineer – thinks of this article? Or the gardener? Or your kids? The audience is part of the goal Aim at a specific audience and define them If you write an article that is supposed to generate new opportunities for your organizations, you are typically aiming at decision makers within a specific industry. So while your neighbor – the software developer – can find your article too shallow and lacking the technical details he is looking for, your targeted audience of decision makers could possible find it...

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

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

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

After working for 2,5 years as Information Advisor and ICT Architect, I had the opportunity to return to the things that I do best: writing, structuring information (modelling) and designing knowledge solutions. Within a few weeks I will start as Knowledge Analyst / Technical Writer at Be Informed in Apeldoorn, the Netherlands. Be Informed and Technical Communication Be Informed is an internationally operating, independent software vendor. I have worked with them from early 2006 until the end of 2008, as an external contractor. The Be Informed business process platform supports administrative processes, that are becoming increasingly knowledge-intensive. The role of technical documentation in this process should not be underestimated. What if we could provide our users with exactly the information they need to perform their task at exactly the right moment. The information could come from various sources (manuals, websites, on-line help) and could involve combinations of software doc...

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.

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 an earlier post, I compared my work as a technical writer with Island hopping: going from one island to another. The truth is that to perform our job well we need information from different sources within an organization. And on the other hand people from different parts of the organization have a need for our skills when it comes to writing and presenting information. In a way we therefor function as information integrator within the organization: gathering information from different platforms and sources and creating output for different depatments (internal customers) and in different formats. As an example: When I created the documentation for my current customer, I gathered information about the product from different deparments and developed the on-line help. As a result, the Sales department became aware of my presence, noticed the quality of the information and asked me to create the Sales information. Currently I am working on a structure for the product specifications. In ...

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