Old Tech - New Tech

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:
  1. Define the goal, audience, and context: Clearly define the context, goals, and audiences. The design of documentation should be goal-driven—from the user’s point of view. Often, a brown paper or moderation session will help you define these goals and requirements. Involving users in this first step helps them understand the process and gives them an ownership stake in the solution. Create models of the goals, models and other important context factors and discuss them with the involved users.
  2. Analyze processes and activities: This is an important step in creating goal-driven documentation and should lead to a model of all relevant processes and activities. Also define the roles of different users within the processes.
  3. Create the overall documentation model: this phase involves creating an overall structure for the product information, as well as linking this product model to the process and context models. Decide what instruments you want to use to disclose the information: navigation, faceted search, decision trees and/or wizards. Choose navigation if you want your users to be free to browse through the information, faceted search if you want to help them find specific information, and decision trees or wizards to help them make decisions or perform a certain action. 

Bringing back some old techniques

In 1991 I had to develop an on-line help system, making use of the state-of-the-art technology of that time. Preparing the structure and content was done in Word Perfect and we used some kind of help generator (X-Help if I remember well) to create the Help application. As this was a very time-consuming process, doing pre-tests to fine-tune the system would be very inefficient. So we came up with a system of using cards to test out several navigation structures without having to build the actual system yet. We used students as test persons.

We made cards of all topics and did two types of tests with them:

  1. We presented the cards one-by-one to the respondent and asked him or her to categorize them in a - for them - logical way. The categories are labeled and ordered by the respondent, resulting in a blueprint of the structure of the help system.
  2. In another session we presented a number of tasks to our respondents and asked them to find the appropriate help. This time the cards were already categorized and ordered with the name of the category on top of the pile. We observed how the respondents 'navigated' through the piles of cards to find the right topic. The results were used to optimize the blueprint of the structure of the help system.
With the results on paper, we started developing the help system.

Using the card method in this era

Well, considering the fact that I can make a semantic model of the outline of a Help System in less than an hour, it seems silly to spend days behind a desk with several respondents to get the perfect outline for a new system. Nevertheless that's what I did for phase 3 of my documentation process.

One of the main advantages of using the card method to gather input for the overall structure, is that you get respondents to provide you input, without introducing the complexity of an IT System and without confronting them with the choices you have already made. You start with an empty table and end with the categories that can be used in your system. Another advantage is that you can create a good bases for acceptance even before you have started developing the system, by getting the right people involved and using their input in the system's blueprint.
 
My approach:
  1. I prepared approximately 20 cards with topics from the current version of the system
  2. I invited 15 respondents for a 30 minutes session
  3. The sessions consisted of three parts:
    1. 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 ask them to make categories of these five cards, each category forming a column on the table.
    2. 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 are done, we review the categories and make final adjustments
    3. In the final step, the respondent writes down the labels for the categories.

Work in progress

Right now I am in the middle of my sessions. As my audience consists of people working in Sales, people working on implementations and people working on product development, it is no surprise that there are three patterns visible in the categorizations. My challenge will be to find a proper way to serve all three of these groups. Work in progress!

Download the Powerpoint and White Paper

Read more about this topic in the White Paper "Improve your product and brand engagment through smart documentation" for the full background story and download the Powerpoint from my presentation on the STC Summit 2013 on:

Register to get updates about future Webinars, articles and presentations on the topic Smart Documentation.

Comments

Post a Comment

Popular posts from this blog

Using the Golden Circle Model in your resume and LinkedIn profile

Image
The last three years I worked as a (senior) business consultant and information architect at software company Be Informed in Apeldoorn, the Netherlands. We worked on an amazing product, a ground breaking model-driven business process platform. And my job was to explain the possibilities of this platform to various audiences. The Be Free program, which I launched in September 2013 was a marketing campaign that targeted on making a wider group of people familiar with the product. The campaign was a great success and I had the feeling that I was really helping people in proving their ideas to their customers and managers. But the interaction was on-line and from a distance, never close enough to really understand their business goals and issues.  The sudden end of my contract with Be Informed, forced me to rethink my professional goals and ambitions. What do I really want? Do I want to be a product marketer, focused on 'pushing' a product? Or do I want to be a business cons
Read more

Improve Product and Brand engagement through smart documentation - A White Paper about the challenge of creating user-centric documentation

Image
For most product manufacturers, delivering adequate documentation is a constant challenge. The increasing complexity of products and the stricter regulations for product documentation often lead to extensive documentation sets with 500+ pages manuals on-line or in print. The question is: how effective is all this documentation? Smart, user-centric documentation Users can be overwhelmed by long, jargon-loaded user manuals, and frustrated by a lack of clear answers. When customers don’t find a solution, blame inevitably falls on the product and the company. Bad documentation - incomplete, unclear, out of date - creates a negative engagement with products and brands. Figure 1. Smarter documentation asks users what they need to know Smart documentation leads users to success and satisfaction. These are the users who share their positive experience with family and friends, and convince them to become customers in turn. Using semantic technology, we can create the smart document
Read more

Laying the foundation for an effective article

Image
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 short and sharp, I don't
Read more