Improving the effectiveness of information

Abstract: Process-driven information: it’s all in the business process design

noreply@blogger.com (Kees van Mansom) — Thu, 16 Feb 2012 06:52:00 +0000

Imagine working at the customer support center of a bank or insurance company, responsible for providing accurate, complete and reliable information to customers. How can you guarantee that the information provided to your customer is enough to prevent possible risks? And, when things have turned out wrong, how can you prove and defend your recommended advice afterwards.

Now imagine you are the manager of the helpdesk: for certain your information needs will be completely different. What you don’t want is another set of manuals, or an additional knowledge base or website: you want the required information available as precise as possible and at the right moment. There-after you need to be able to reproduce how this information could affect the decisions made by you or your customer. In essence, simple straight through processing.

I have made an abstract, titled “Process-driven information: it’s all in the business process design”, for the Building Business Capabilities conference. If accepted, I will demonstrate in the Business Architecture track of this conference how information and documentation can be embedded in the process and made actionable.

In this presentation we will learn:

How process-driven information can lead to more efficiency, better compliancy and lower risks
Why documentation of our processes and products can be seen as a result of our processes, modeled by the business itself and growing with the maturity level of the organization
How (semi-)automatic decisions, calculations and advices can be directly derived and embedded in the process
Who will benefit from this approach.

The conference is from October 28th until November 2nd 2012 in Fort Lauderdale, Florida.
I expect feedback on this abstract around the 31th of March 2012 and will start this blog to share and discuss my thoughts on this topic.

Working on a new concept for process-driven documentation

noreply@blogger.com (Kees van Mansom) — Tue, 07 Feb 2012 07:02:00 +0000

Yesterday I started working on a new concept for process-driven documentation. The goal is to provide a method that enables us to implement goal- and process-driven documentation during the implementation of new Business Process solutions.With this new concept I want to revive the 'old' Documentation 3.0 idea and implement it in a Business Process context.
Main topics are:

How process-driven information can lead to more efficiency, better compliancy and lower risks
How documentation of our processes and products can be seen as a product of our processes, modeled by the business itself
How a Grow Live approach (instead of Go Live) can help us to continuously improve processes and information

I am working on this topic together with Thei Geurts, with whom I worked together on the Documentation 3.0 topic in 2007 and 2008. Some of you might remember our presentations at the STC Conference in Philadelphia or the ISTC Conference in Nottingham, both back in 2008. With this new view on process-driven documentation we will bring our ideas to a much broader audience. Stay tuned, as I will post some of the work in progress here.

Using a standard notation method for audience and tasks analysis

noreply@blogger.com (Kees van Mansom) — Sun, 05 Jun 2011 11:23:00 +0000

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 with the Business Architecture Component in TOGAF.

In the Archimate business layer we create a model of the business context in which our to be implemented solution or change will take place. The following concepts are used:

Actor: organizational identity capable of actively performing behavior. Examples of actors are employees, departments, and business units. In a more complex environment customers or groups of customers (in branches) can also be seen as actors.
Business role: a named specific behavior of a business actor participating in a particular context.
Business function: a unit of internal behavior that groups behavior according to, for example, required skills, knowledge, resources, etc., and is performed by a single role within the organization.
Business process: a unit of internal behavior or collection of causally-related units of internal behavior intended to produce a defined set of products and services.
Business service: the externally visible functionality, which is meaningful to the environment and is realized by business functions and business processes.

Source: Archimate

How to use this approach as a technical communicator?
As technical communicators we are familiar with the concepts of actors, roles, functions and processes, but the thing is we never call it that way.

An actor is to us the audience, defined as a group of people, an organization or group of customers.
The role is in fact what we could describe as 'the user'; a particular type of person within the audience.
Processes and functions are what we would call tasks and activities.
The Service is for us a goal-related set of tasks and activities, used as an umbrella for our task-oriented descriptions.

We could use a simplified version of the Archimate model to document how our audience, user types and tasks and activities are related to each other.

With this simple contextual diagram we can create an overview of our audiences, user types, activities and tasks and relate these to each other. During the actual writing of the documentation, we can benefit from this knowledge.

Create models instead of writing reports
There is no point in writing down long reports about the composition of our audiences. In my opinion the goal of doing an audience and task analysis has always been to document some context information to benefit from it as a writer. No customer or colleague would ever ask me for this document. Can we then save ourselves the trouble of documenting our audience and tasks analysis at all?

Let's put it this way: Say you have made some wrong assumptions at the start of your project, based on information provided to you by your customer. How can you ever analyse the problem and solve it if you have never recorded it properly.

Creating models of the context - audiences, roles/types, tasks and activities - makes it easier to create a quick overview of relevant aspects, without the burden of writing a report that no one ever reads. The model is the information.

In my next articles I will get into more detail on how to use models to describe the context of your information and how we can actually use these models in our documentation. If all goes well I can even add some actual examples from my day to day work at Be Informed in it.

The Technical Communication Framework (TECOF)

noreply@blogger.com (Kees van Mansom) — Mon, 23 May 2011 06:28:00 +0000

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 and defining the relevant applications and data.
Technology Architecture: describes the technical infrastructure
Opportunities and Solutions: this concentrates on how the architecture will be implemented
Migration Planning: creating a viable implementation and migration plan.
Implementation Governance: this establishes the connection between the architecture and implementation organization.
Architecture Change Management: monitoring governance requests, new developments and changes in the business environment.

A Framework for Technical Communicators

When looking at the TOGAF Framework for ICT Architecture / Enterprise Architecture I couldn't help but noticing the similarities between documenting an enterprise architecture and writing user documentation. Surely there are differences: the audience, the level of detail in the information, the overall governance. But the framework could be easily modified to serve as a basic framework for technical writing:

Goals and principles: this describes in scenarios how the new product or solution will meet the business goals and strategic objectives and address the stakeholder concerns when implemented.
Actors, roles and processes: models that describe how the goals and principles of the product or solution can be mapped to actors (audiences), roles, functions and tasks.
Functions: this focusses on identifying and defining the relevant components and functions in the product or solution that you are describing.
Technology: describes the technical details of the product or solution.
Solutions and applications: this describes in scenarios how the defined actors (the audiences) can benefit most from the possibilities and features of the product or solution.
Migration: describes the necessary steps to migrate existing data to the new product or solution (if applicable).
Implementation: this describes how the new product or solution can be embedded within an organization or - with consumer products - how the product can be launched successfully.
Change Management: monitoring new developments and changes in the product or solution and implement them in the documentation.

Although I am aware of the fact that this framework will not be 100% useful for every documentation project and for every technical writer, I think it gives us a good starting point for an overall method and set of tools that can help us in our daily work.

TECOF

Every framework needs a name, so I might as well choose one to start with. What about: The Technical Communication Framework (TECOF)? Suggestions for a (better) name are welcome: don't hesitate to use the comment box to drop your suggestions for an alternative name.

It would also be nice to see organizations like STC and/or ISTC adopting this framework and promoting it into their community for further development. To make it a standard framework the development and usage should not be restricted to any society, institute or company.

A structured approach to audience and task analysis

I started this series of blogs with the statement that we - as technical communicators - can learn from ICT Architects. I have already showed the similarities in the framework, now it is time to go into detail. Next time we will look at a structured approach to audience and task analysis.

I will explain how we can use a standard notation method - based on the Archimate standard for ICT Architecture - to describe our audiences and their tasks in terms of actors, roles and processes.

An Open Framework for Technical Communicators?

noreply@blogger.com (Kees van Mansom) — Mon, 16 May 2011 07:13:00 +0000

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 area 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 the process of creating it. In the same way as the Open Group has created a framework for Enterprise Architure, a community of technical communicators - supported by for instance the Society for Technical Communication (STC) or the Institute for Scientific and Technical Communicators (ISTC) - should stand up and define a set of tools, templates and methods for technical communicators, presented as an open framework.
There is absolutely nothing wrong with the current education programs and standards, but what we need is something that bundles all efforts and transforms it into an industry standard. And in my opinion this standard should focus solely on the process of documentation creation instead of on the end product of it.

How do we benefit from such a framework?
Do you get tired of explaining over and over again why you need that audience analysis or why you want to pretest your documentation? Well, as an ICT Architect I only have to say that I have to comply to the TOGAF standards and all discussion about needed analysis and modelling time is gone. So having our framework for technical communication would not only give us a good reference on how to do thing, it will also make it easier to explain why we need activities like audience analysis and pretesting. Not complying to the framework is still a choice, but it will be an explicit one.

What do we need to create such a framework?
Well in fact most of us probably have an idea what should be in it. We have a lot of knowledge, best practices and research data available at for instance the STC and the ISTC. In my opinion the focus should be on bundling and prioritizing the information that we already have, to produce a version 0.1 of our very own Technical Writing Framework. By making use of the international community of technical writers and the possibilities of communities on the internet, we can evolve this method to the technical communicator's equivalent of TOGAF.

How do we give it the status of a real framework for technical communicators?
Well I know it might sound too easy, but in my experience something "new" becomes "common" just by accepting it as the standard and start communicating about it in this way. And yes, we need a website, we need a name for the framework and we need people to spread the news and share their experiences.

I hope this is enough food for thought for now. Don't hesitate to drop your opinion in the comment box or start a discussion.

Next time I will continue my exploration of lessons learned as an ICT Architect. First I will look at the similarities between TOGAF and the process of writing technical documentation and come up with the raw outline of a framework for technical writers. Next I will talk about using modelling techniques - similar to Archimate - that technical communicators could benefit from in the earlier stages of their writing project.

Lessons learned from ICT Architecture

noreply@blogger.com (Kees van Mansom) — Mon, 09 May 2011 09:54:00 +0000

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 project as a technical writer: Where should we start?
I have always learned that a good starting point for user-oriented documentation is the audience analysis (Wapenaar et al., 1989). This will provide us with more or less detailed information about our audience in terms of age, gender (percentages), religions, regions, languages and education levels. Suffice to say, this might be enough to start writing a flyer or brochure but for a user-oriented documentation solution this is not sufficient. An analysis of user tasks and processes should therefore be required, but is often regarded as too expensive and time consuming.

Processes in ICT Architecture
In the past 1,5 year I have worked as an ICT Architect at the IT Services Department of USG People the Netherlands and made Project Start Architecture Documents for several new ICT solutions. Although they will probably not see the similarity themselves, ICT Architects face a similar challenge as technical writers when it comes to describing a platform, system or application. It is not coincidence that architecture frameworks like TOGAF and DYA made processes an important artefact within the enterprise architecture. In fact the business architecture - centred around goals and processes - might as well be the most important of the four pillars within the TOGAF framework.

According to TOGAF, Business Architecture is a disciplined approach to realize business models and is meant to serve as a business foundation of the enterprise to enhance accountability and improve decision-making. Business Architecture's value proposition is to increase functional effectiveness by mapping and modelling the business to the organization's business vision and strategic goals.

So how does this help us?
What I will do in this series of blogs is use the lessons I have learned as an ICT Architect and translate them to a method that could be used by technical writers. Although I will focus on the first phases of the writing process and compare them with similar steps in defining the Business Architecture, I will also look at the overall architectural framework and see what we can learn from it.

Back to technical writing

noreply@blogger.com (Kees van Mansom) — Tue, 03 May 2011 07:42:00 +0000

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 documentation, process descriptions and other types of instructions.

I am excited to return in the world of technical communication and semantic technology after 2,5 years of absence. As mentioned back in 2008 (in this blog series) our users are facing an overload of information. The use of semantic technology could well be the next step in the evolution of technical communication.

Not just technology
However, the technology alone is not enough to improve the effectiveness of our documentation. We need a goal-driven, user-centric approach to get the most out off this technology. One of the first projects I will do at Be Informed is documenting scenarios for the optimal usage of their own product. This should lead to a fully task-based knowledge bank, providing different audiences with exactly the information they need to get the most out of the Be Informed business process platform. I will use this blog to document my approach and results.

Related articles
* How Information becomes Knowledge
* How Knowledge becomes Usable

A new corporate Intranet

noreply@blogger.com (Kees van Mansom) — Fri, 11 Sep 2009 08:24:00 +0000

In 2006 I spoke at the STC Conference in Minneapolis about improving the effectiveness of corporate Intranetsites by using semantic technologies. At that time I was doing projects for the Dutch company Be Informed, involving combinations of decision support and case management. So my presentation was focussed on these aspects and on making optimal use of the knowledge within organizations.

Now, two years later, I am again working with corporate Intranetsites. This time for USG People, the company I work for since the 1st of January 2009. Goal is to implement a new Content Management System within the organization and use this to create Intranetsites for all of its subsidiaries. Subsidaries like Start People, Unique, Content, Creyf's and Secretary Plus all will implement their own Intranet based on this single platform. My role will be to make sure that they learn to make the most out of this new platform.

Documentation 3.0

noreply@blogger.com (Kees van Mansom) — Tue, 02 Dec 2008 07:45:00 +0000

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 means it delivers a personalized solution for each inidividual user and is based on their demands. We use the context situation of users - by getting information out of systems and databases and/or by asking them questions - and bridge the gap between the offered content and the context.

The documentation should also be flexible and adaptable to constant changes in both content and context. It uses multiple sources, with an increased focus on collaboration throughout the whole product life cycle. To do so it uses semantic technology as an add-on to content management systems and a knowledge-centered approach to documentation. Documentation 3.0 also changes the role of the technical communicator, offering new opportunities.

Semantic technology

Documentation 3.0 is like the Web 3.0 movement based on semantic technology. Semantic technology is the technology that enables us to move from providing information to providing knowledge. But what is knowledge and what is information?

Knowledge is the interpretation of information within its context. It makes it possible to act and react in a proper way and make decisions.

With semantic technology we are able to make the shift from being information providers to being knowledge suppliers and helping users take effective action.

From product centric to process centric documentation

noreply@blogger.com (Kees van Mansom) — Tue, 18 Nov 2008 11:00:00 +0000

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 some copy & paste, but basically we still produce separate manuals.

Process centric documentation
With the coming of content management systems our clients no longer ask us to write a manual for one product, but demand us to deliver chuncks of information that can be used for several products and in several media. It’s like the box in the story of the little prince – the sheep you want to see is inside. In this phase the focus went from a strictly product approach to a process centric approch. Re-use seems to be more important that a 100% match with the audience. Creating documentation also becomes a collaborative process for which we use standard tools.
Because of the re-use issue, we need to work with chunks of information – typical functional descriptions because they are easy to isolate. Task based documentation becomes a challenge, although it is still possible to create it by describing standardized processes.

What's next?
The possibilities of semantic technology will give documentation a new impulse, leading to a next phase in documentation: documentation 3.0.

Documentation 3.0

noreply@blogger.com (Kees van Mansom) — Fri, 31 Oct 2008 12:13:00 +0000

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 screen. So you should be aware of a lot of context variables if you create an instruction.
If you would put all those instructions in a manual, this would mean that the total amount of information would increase. And one of the major issues is that our users are already confronted with an ever increasing information overload. There is simply too much information: from too many sources, in too many formats and through too many channels. And only a small part of it is relevant to our users.

How can we solve these problems?

Improving search and aggregating content just is not enough to solve this problem. Also reconstructing content components to new meaningful products or mashups don’t help.
It just multiplies the enormous volume of content that we are already facing. The only way to solve this issue, is by adjusting the information to the context of individual users.

Next time I will talk about the first two phases in the development of Documentation. Enjoy the weekend!

Kees

I'm back

noreply@blogger.com (Kees van Mansom) — Thu, 23 Oct 2008 11:35:00 +0000

Well, it has been a busy 6 months since I wrote my last blog. In the meantime I have visited two conferences and worked out some interesting stuff about the topic of using semantic technologies in documentation. I will post my ideas in the coming weeks.

What did I work on? I was hired by Be Informed to create an overall knowledge infrastructure - in models. You can see a part of it on their website: http://www.beinformed.nl/. Untill the end of the year I will be working on this.

In January 2009 I will start as a Senior Information Advisor at USG People The Netherlands. After 12 years of working as a consultant in the ICT world, this is a welcome change. The core business of USG People is employment services and I will be working in their internal ICT department and advising the management of the operating companies on their ICT plans and projects.

USG People is a specialized provider of employment services in Europe, focusing on the market segments general and specialist temporary employment, professional secondment and projects, HR services and customer care. We provide this range of services through our independent operating companies. Our companies are active in thirteen European countries: Austria, Belgium, Czech Republic, France, Germany, Italy, Luxemburg, the Netherlands, Poland, Portugal, Slovakia, Spain and Switzerland. USG People shares are listed on the stock exchange NYSE Euronext Amsterdam. (Source: http://www.usgpeople.com/)

Cover article in the Intercom: The flexible Intranet

noreply@blogger.com (Kees van Mansom) — Thu, 03 Apr 2008 06:13:00 +0000

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.

Creating a metamodel for your Knowledge Bank

noreply@blogger.com (Kees van Mansom) — Tue, 05 Feb 2008 06:31:00 +0000

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 planned to be created in the future - share one thing: they all offer a view on the product. For this reason I decided to use a model of the product as the binding factor - or integration layer - for all knowledge banks.

Lessons learned from Documenting Product Development

noreply@blogger.com (Kees van Mansom) — Tue, 29 Jan 2008 06:43:00 +0000

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 its own documentation structure. Then find the similarities in the models to create one overall integration model to bind the different models.

Define the rules for your models before you start modelling
As a technical writer I am used to first structure my information, before I start writing. The idea of making models of information, is not very different from making a content hierarchy for your documentation. As described in my earlier blog I started with making a composition model for the product range. With only one type of concept and one type of relationship between the concepts, it became very hard to determine on which level of the model you were. So I introduced different types of concepts and relations while I was making the models.
Within a few days the structure became more and more complex and not consistent at all.
This situation can be avoided by first making a design for your models:

Describe the concept types used, for instance: "Product", "Product module", "Function" and "Component"
Define the types of relationships that are allowed between the specific concept types. For instance: "Subclass of" to connect a "Product Module" to a 'Product"
Create a list a the content types that you want to add per concept type, for instance: "Definition", "Description", "Instruction" and "FAQ".
Optional: add label types for language versions and additional index entries.

In my next blog I will demonstrate what the effects of these lessons learned were on my project.

Article "How knowledge becomes usable" in Communicator

noreply@blogger.com (Kees van Mansom) — Thu, 10 Jan 2008 08:38:00 +0000

In my article "How knowledge becomes usable" - published in the Winter edition of Communicator - I explain how you can incorporate knowledge-driven design in information products. The Communicator is the quarterly journal of the Institute of Scientific and Technical Communicators (ISTC). The article is a follow-up on my presentation at the ISTC Conference 2007 in Liverpool.

If you are a member or a subscriber of Communicator, you automatically receive this issue. 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.

Documenting product development

noreply@blogger.com (Kees van Mansom) — Tue, 08 Jan 2008 06:18:00 +0000

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 component design documents have a structure that is based on the functionality of the specified component. Every document has a different structure. One of the requirements is that these documents remain in Word and that the audience will always get the latest version of these documents.

The main problem with these documents is, that it is impossible to make a match between the functional requirements and the component design. The structure of the documents is completely different.

Approach

I decided to first make a model of the product, using a composition model.
Next step would be to add the content of the product requirements to the model
Then I would add links to the relevant component design documents.
And finally I would make a knowledge bank of it with navigation.

I use the Be Informed Productsuite here because it offers support for the product modelling, the adding of content and on the fly creation of a knowledge bank (web application)

Making a composition model of the product

This model was not based on any of the existing documents. Instead I analyzed the structure of the product and made a series of models out of that. I used small models and connected them to each other with reference concepts. A reference concept is a concept in another model that you refer to.

The advantage of using smaller models is, that they are much easier to maintain.

Technical writers as information integrators

noreply@blogger.com (Kees van Mansom) — Thu, 27 Dec 2007 10:32:00 +0000

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 this role I am becoming more and more an in- and output box. Put in the raw information in any format and get the information you need for a specified audience and in a customized format.

New article in Intercom

noreply@blogger.com (Kees van Mansom) — Mon, 17 Dec 2007 10:05:00 +0000

In March 2008 my new article "The Flexible Intranet" will be published in Intercom, the monthly magazine of the Society for Technical Communication. In this article I will examine the typical problems found in a corporate intranet site and demonstrate how knowledge-driven design can improve the effectiveness of intranet sites.

In the article I use the example of a helpdesk that delivers support for mobile phones. With this example I will demonstrate how an effective intranet site guides the helpdesk employee toward the information and presents the answers to the questions they are confronted with.

Saul Carliner, an internationally known expert on technical communication, contributed to this article.

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.

Island hopper

noreply@blogger.com (Kees van Mansom) — Tue, 11 Dec 2007 07:22:00 +0000

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 implemented an enterprise content management system to force their employees to work together in a shared environment. Others used a workflow or case management approach. All of these measures required people to change the way they are working, forcing them to follow the rules of the newly implemented system.

So how can we create permanent and flexible access to all this information without forcing the people on these islands to work in one shared environment?
In my upcoming posts I will illustrate how a knowledge driven approach can help us gather information from subject matter experts, linking different sources of information and presenting information tailored to the needs of internal and external audiences.

About knowledge modelling: attributes

noreply@blogger.com (Kees van Mansom) — Wed, 05 Dec 2007 08:39:00 +0000

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 could not find the product tag. I bought it in 2006"

Service desk employee: "Does it have a silver front or a black front?"

You: "It has a silver front"

Servce desk employee: "What color is the Power indicator?"

You: "It is red"

Service desk employee: "You have the SW457"

The Service desk employee can now open the specific information for this product type. When we use the same principle on a web site, we can help our users determine which type of product they have and lead them to the information they need.

About knowledge modelling: simple hierarchical models

noreply@blogger.com (Kees van Mansom) — Mon, 03 Dec 2007 06:32:00 +0000

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 type 'is a', e.g. car is a vehicle. A taxonomy is also known as a concept model and is vital to representing knowledge.

A third type of knowledge model is the composition model. A composition model shows the way a knowledge object is composed of its constituent parts. All relationships in the ladder are of the type 'Part of', e.g. wheels are part of a car. A composition model is a useful way of understanding complex entities such as machines, organisations and documents.

The strength of using models is that they enable us to quickly create a graphical overview of complex information. When used stand alone, they are nothing more than that. But combined, they open up a whole new world.

Imagine yourself now writing documentation for a complex technical product and think of the opportunities for using taxonomies and composition models in addition to your content structure. It would add a new dimension to your documentation. Your readers / users can now access your task oriented information through the hierarchical content structure, while they can use the taxonomy to quickly determine what sort of product or part we are talking about. By also adding a composition model you can enable them to zoom in on the more functional information.

Next time I will talk a bit more about combining models and adding for instance attribute models.

About knowledge modelling: Why do we need it?

noreply@blogger.com (Kees van Mansom) — Fri, 30 Nov 2007 09:14:00 +0000

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 questions that can be answered with yes or no

wizards: help users to answer a complex question by asking them simple questions and guiding them to the answer that suits their personal situation and context

facetted search: narrow down search results by providing contextual aspects that filter the results of search actions

Incorporating these characteristics in our information products, requires us to create models of the information and its context. Working with these knowledge models adds an extra dimension to our technical writing.

Creating better information products is all about thinking in scenarios. Knowledge modelling is a good way to record and visualize these scenarios. In my next posts I will visualize the process of creating knowledge models.

Please feel free to post any questions you have about this topic. This is an interactive weblog, so don't hesitate to make use of it.

Additional sources of information about knowledge modelling:

http://www.csd.abdn.ac.uk/~apreece/ebiweb/papers/serrano.doc

http://www.epistemics.co.uk/Notes/90-0-0.htm

http://www.tlainc.com/articl67.htm

Be Informed announces international release

noreply@blogger.com (Kees van Mansom) — Thu, 29 Nov 2007 07:37:00 +0000

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 with a URL.

In my upcoming article in Communicator - the magazine of the ISTC - I will demonstrate how you can improve the effectiveness of documentation with tools like Be Informed.

New Machinery Directive as of 2010

noreply@blogger.com (Kees van Mansom) — Wed, 28 Nov 2007 06:30:00 +0000

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 documentation systems that stand the test of time. During the whole life cycle of a product the documentation has to be adjusted to changes in the product, the context in which it is used and changing perceptions on health and safety issues. Taking into account that all machinery must be accompanied by a translation of the instructions in the language of the country in which the machinery is to be used and by the instructions in the original language, you can imagine that this will lead to a very complex situation.

A structured documentation process in combination with the appropriate tools can help us solve these issues:

Set up a linear process for the creation of all documentation products, involving all necessary steps from defining the goal, audience and context of the product and its documentation to the final pretest and translation of the documentation products.
Set up processes for updating the documentation products, including the translations.
Choose appropriate tools for the authoring process, taking into account that technical writers, illustrators, subject matter experts and translators have to work in a shared environment.
Choose appropriate tools for the publishing process: depending on the product type and user group you will have different media. Electronic products typically feature on-line help in combination with a printed manual. In addition to these documentation types, instructions can be published on websites.

Please feel free to post you experiences with these kind of challenges!