Improving the effectiveness of information

In this series of articles you can follow my process in writing a new article on Robotics. In the  first episode  I explained my approach towards writing, the  second article  focussed on setting the goal, choosing an audience and finding the right approach. Now that we have a clear vision on goal, audience and approach, it is time to start setting up the structure. Writing requires a structured approach Writing is all about structuring your thoughts. And although this is a process that most of us do in a more implicit way, it sometimes helps - and is actually best practice - to write down your structure on a very high level. The goal of my article is to change the opinion of the reader towards accepting Robotics as a something that brings value to a business and motivates employees, rather than being limited to reducing FTE. So the structure of my article should be build up around the motives used to build up this case. As I want my article to be shor...

We’re at the final episode in this blog series about writing effective articles.  In this series of blog posts I have explored the criteria for a successful article, providing you some best practices, lessons learned and examples from my own work.  The recipe for an effective article So what is the recipe for an effective article? For those of you that just jump in, I would recommend going back to the first blog post. For those of you who have followed me all the way through, let’s summarize it: Start with the definition of your goal: What do you want to achieve with your article? Add to it a clear definition of your audience: Who are you writing for? Now – while keeping an eye on goal and audience – make a sketch of your story: What should the high level structure of your article look like. Detail the building blocks of your story and place them in the high level structure Gather the information you need for your article – in a raw form - and start placing it in ...

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

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 engineering , a requirement is a singular documented physical and functional need that a particular product or service must be or perform. It is most commonly used in a formal sense in systems engineering , software engineering , or enterprise engineering . It is a statement that identifies a necessary attribute, capability, characteristic, or quality of a system for it to have value and utility to a user." Source: Wikipedia During the Building Business Capabilities conference 2012 in Fort Lauderdale, we are going to develop a working model-driven business application, based on the input provided by the audience. And although this will be in a "lab" situation, we want to stay as close to a real life situation as possible. And then working with requirements is an essential element. Both requirements and the Be Informed modeling artifacts (models, profiles, custom meta models) are aimed at the same goal: allowing the stakeholders of the system to ...

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

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

You probably recognize this situation: You have to write a manual, product leaflet or text for a website and you need some information about this specific topic. The information about the topic is available within the organization, but you have to gather it from different people from several departments. And they don't like you messing with their content. They want to keep control over it. Sometimes our job as technical writer is like moving from one island to the other, building bridges and demolishing borders. If you - for instance - need to describe a product, you first travel to the island of the product developers to gather the product specifications. Next you can go to the marketing department to get some of their sales statements about the product and you might want to hop to the Service department to get the ins and outs of their servicing approach. Does this sound familiar to you? I have found this situation in all kinds of organizations. In some cases these organizations ...

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

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