Knowledge Delivery Basics

The following is a series of tips for crafting effective knowledge deliverables which I have developed over my 20 some years in the field. Whether your deliverables will be in the form of written documentation, frontal presentation or online training (CBT) you will find these tips to be equally useful.

My recommendations to you, dear reader, are two:

• Learn it, live it, love it. You’ll be happy you did. It will improve your deliverables immensely.
• When you begin a project, explain to your customer that you plan on following these guidelines and enlist their participation to help you to execute the project effectively. You will come off as a true professional who knows his craft.

User Roles

The first thing you need to think about when preparing knowledge deliverables for a product is User Roles. Who are the people who are going to use this system; or more accurately, in what different ways will this system be used by different people?

An example of this is a system for running a police investigation. At the very least there will be Operators who input information into the system, Investigators who view the gathered information and form conclusions and Administrators who control access to the system and perhaps generate reports for management. These user types, or user roles, have very different tasks to fulfil and will use the interface very differently.

Defining user roles will enable you to give guidance for each role separately, rather than simply describing the interface and letting each user figure out which parts are relevant to him. Further, once you have defined a user role, it is much easier to figure out the recommended workflow for using the system, which will serve as the outline for your knowledge deliverable, and help you to keep your deliverable on target.

In truth, the flow of each user role should be built into the interface. When they login to the system, only the options relevant to them should be available. And the structure of the interface should support the flow for their specific user type. But in my experience this is almost never the case, which is good news for us knowledge delivery specialists because if the UIs were truly self-explanatory then we would be out of our jobs.

Assuming user roles and flows have not been defined by the time that you enter the fray, you should gently push your customer to define them before you get started. Your deliverable should always include a recommended workflow if at all possible. If there are truly many possible workflows, start by describing the most straightforward scenario and then explain how the workflow is adjusted for various circumstances. Without your guidance only the most motivated users will figure out the ideal workflow in the system, while the rest will just conclude that the product is less than optimal. Your job is to make sure that anyone who has put in the time and effort to access your deliverable receives clear and easy guidance on how to maximize the product's capabilities. Using this tip will make their experience as positive as possible, to everyone's benefit.

Keep On Target (Minimization)

There are three shining stars that guide us as we prepare knowledge deliverables. They are: minimization, clarity and brevity. What you deliver must include exactly what the reader needs to know, not one drop more or less, and it must be presented in a manner that is as clear and concise as possible both in terms of time and words. This tip describes minimization (tips about  clarity and brevity are coming soon).

So once you’ve figured out the user roles and flows, find out what the user already knows and keep that out of your deliverable. If they already know it, it is a waste of your time to tell them and a waste of their time to review it. In addition, and this is very important, the slightest bit of extra information in your deliverable will very likely confuse the user. Users are often searching for answers to specific questions that have arisen. When they come across something obvious that sounds like it may relate to one of their questions, they'll often read a meaning into it that was not intended. I’ve seen this again and again, so I beg of you, please avoid extra information like the plague. (Tip: If you ever do feel the need to add a tidbit that may already be obvious,  express it in a way that makes it clear that you're just making sure that they are aware of this point, that way they'll know not to read anything extra into it.)

As an example of unneeded information, I will go back to when I was a junior technical writer (back when we rode dinosaurs to work), and my specialty was network management systems. People would make comments like, “Cool, so you know how to manage networks!”, which was considered cool back then. To which my answer (with a slight blush) was, “Well, actually no. But I can instruct network managers on how to use this system to better accomplish the network management tasks that they already know how to do.” The users already know how to manage networks, so it is obviously correct to keep network management out of the deliverable, along with anything else that they already know.

In addition to being aware of  what the users already know, you must also take into account what they don’t know. Sometimes your deliverable will have to include much more than what the product actually offers. As an example, let’s once again return to ancient times when I wrote a manual about a network management system. The product used a third-party network management platform as a base, and added some features that would help them manage their product (which was a network hub). The developer described to me in detail how to use the system to manage their hub. Realizing that the user might not know how to use the third-party management platform, I included information about that as well. It turned out that most of the manual dealt with the third-party management platform, and only a small part was about the features that were developed to support my customer’s product. I was surprised and pleased when the developer acknowledged that although he had envisioned an entirely different document he recognized that this was in fact what the user needed. So make sure that your deliverables include everything that the user needs to learn in order to gain the full benefits from the product.

So how can you find out what the users know and what they don't know? The product manager should have a meticulous understanding of the product’s user profile, so he is your go-to guy for this information.  Milk him for whatever he can tell you about what to expect from the end user. Then create your deliverable with that information in mind.

So keep on target. Tell your users everything they need to know, and not one drop more. They will thank you for it.

Re-use, Maintenance and Word Usage

As the number of knowledge deliverables for a set of products increases, I would recommend you take into account a few more items when you setup your deliverables. They are: planning for re-use of the material you prepare, ease of maintenance of your material, and ease of word usage.

Re-use: Many product lines have similarity between products. The products often have components or procedures that are identical or nearly so. So it makes sense to prepare these sections of the deliverables only once and re-use them across the product line. So identify ahead of time which sections can be re-used, and build them so that they apply to all relevant situations. Once you do this, it is simply a matter of copy and paste, and voilà! it’s coffee time.

Another aspect of re-use is publishing to various output types. For example, user manuals are often used as online help. With the proper tools (I’ve used AuthorIt but there are plenty more), you click one button to get Word, another to get PDF, a third to get CHM (Windows HTMLHelp) and a fourth to get online help in a Web HTML form supported by standard browsers. The time spent in setup is more than worthwhile when the deadline is upon you and the deliverables practically create themselves while you sip your latte.

Maintenance: Be sure to strictly follow the minimization guidelines described above. Any additional information you include is another thing that needs to be maintained. So if the user does not need to know it, keep it out. Another recommended practice for easy maintenance is to mention each item only once and cross-reference it throughout the document as needed. That way, when a product detail is changed, you will be spared the painstaking and error-prone activity of tracking it down and updating it throughout the document.

Translation and word usage: There are two basic rules for word usage; keep the language simple and use your terms consistently. Keep in mind that very often your documents will end up being used by people for whom English isn't their first language, and maybe not even their second. So leave out the highfalutin language and choose words that your car mechanic would understand. Also, use your words consistently. That means one word for one meaning; don't alternate between different words with the same meaning and don't use the same word with different meanings in different places. So, for example don't refer to different items as the device in the same section. Also, don’t alternate between using the word case and investigation to describe the same entity.

These are always important guidelines but if you anticipate the document being translated into other languages then this becomes even more essential. Simple words often translate better than more rarely used words. And attempting to translate a document with inconsistent word usage is a recipe for disaster.

Another tip for translation: Prepare a glossary. This should include a list of product names which should not be translated at all, as well as a list of terms that are specific to the product usage and need to be translated accordingly. For example depending on the product you are documenting the word target can mean a person of interest, the location to which data is being transferred, or any number of other things. Clarifying these terms for the translator will lead to a better translation.

Again, these considerations take on more importance as the number of products, the number of knowledge deliverables, and the number of knowledge deliverable platforms increase. 

Shimon Brody

General Manager 

Amethyst Writer Ltd.