You are on page 1of 21

ITIL

KNOWLEDGE DOCUMENT STANDARDS


REVISION: 6

APRIL 27, 2012

Document File Name: ITIL_Knowledge_Document_Standards_06.doc

Project Manager Approval:

Date:

Project Sponsor Approval:

Date:

REVISION CHART
The Revision Chart contains a history of each revision to this document.
Revision

Primary Author(s)/
Project Manager

Description of Revision

Date
Completed

01

SRG

Revision to templates

08/24/2011

01

SRG

Revision to Master List and Attachments

08/24/2011

01

SRG

Revisions to links in the document

08/24/2011

02

SRG

Revised Self Help Library URL

08/26/2011

03

SRG

Revisions to Section 4.2 and 5.2.1

02/14/2012

04

BP

Revisions to Section 5.2 and 5.2.1

03/08/2012

05

SRG

Revisions to Section 4.3

04/03/2012

06

MR

Revisions to Sections 4.3.1, 4.3.2, 4.3.3, 4.3.4 and


4.3.5

04/27/2012

-1-

GLOSSARY OF TERMS
The glossary lists fundamental terms used in the body of the document.
Terms

Definitions

CTM

Communications and Technology Management

ITIL

IT Infrastructure Library

BMC SD

Service Desk Express

BMC KME

Knowledge Management Express

SME

Subject Matter Expert

KB

Knowledge Base

COA

City Of Austin

UFFA

Use It, Flag It, Fix It or Add It

Subject

defined as the application, process, etc. being


documented in the KB document

-2-

CONTENTS
1.0

INTRODUCTION.................................................................................................... 5

1.1
1.2
1.3
1.4

PURPOSE............................................................................................................... 5
INTENDED AUDIENCE............................................................................................. 5
SCOPE................................................................................................................... 5
ASSUMPTIONS....................................................................................................... 5

2.0

KNOWLEDGE BASE DOCUMENT PROCESS STANDARDS......................................6

3.0

KNOWLEDGE BASE DOCUMENT GENERAL INFORMATION.................................7

3.1

DECIDING WHAT TEMPLATE TO USE......................................................................7

4.0

KNOWLEDGE BASE DOCUMENT CONTENT STANDARDS.....................................8

4.1

HOW TO TITLE THE KNOWLEDGE BASE DOCUMENT...............................................8


4.1.1
4.1.2
4.1.3
4.1.4
4.1.5

4.2

IDENTIFY KNOWLEDGE BASE DOCUMENT USER....................................................9


4.2.1
4.2.2
4.2.3
4.2.4
4.2.5

4.3

5.1

Maintenance Review................................................................................................19
Flagged KB Document.............................................................................................19
Proactive Review.....................................................................................................19

OTHER BEST PRACTICES................................................................................... 20


MASTER LISTS..................................................................................................... 20
5.1.1
5.1.2

5.2

Error Message Template Content for Fields.............................................................10


How to.................................................................................................................12
Problem/Solution.....................................................................................................14
Reference.................................................................................................................16
Decision Tree USING THIS TEMPLATE IS NOT RECOMMENDED...............18

REVIEW OF KB DOCUMENTS............................................................................... 19
4.4.1
4.4.2
4.4.3

5.0

For Resolution by the Service Desk...........................................................................9


For Resolution by specific WORKGROUP(S)..........................................................9
For Self Help Resolution............................................................................................9
For Reference by specific WORKGROUP(S)............................................................9
For Self Help Reference.............................................................................................9

CONTENT TO INCLUDE BY TEMPLATE TYPE..........................................................10


4.3.1
4.3.2
4.3.3
4.3.4
4.3.5

4.4

Example of Error Message Title:...............................................................................8


Example of How toTitle:........................................................................................8
Example of Problem/Solution:...................................................................................8
Example of Reference:...............................................................................................8
Example of Decision Tree:.........................................................................................8

Storage Location of Master Lists.............................................................................20


Examples of Master Lists........................................................................................20

REFERENCING/LINKING AND ATTACHING DOCUMENTS........................................21


5.2.1
5.2.2

Storage Location of Attachments.............................................................................21


Examples of Attachments.........................................................................................21

-3-

1.0 INTRODUCTION
1.1

Purpose

The purpose of this document is to provide guidelines and standards for submitting a
Knowledge Base (KB) document in Service Desk (BMC SD).

1.2

Intended Audience

This document is intended for any City of Austin (COA) employees who submit KB documents.

1.3

Scope

This document gives detailed information on KB Standards only. This document does not
provide instruction on how to use BMC SD or BMC KME. For detailed instructions on the BMC
SD or BMC KME refer to the manuals stored on the ITIL SharePoint:
http://coawss3a.coacd.org/sites/ITIL/Knowledge/Knowledge%20Management%20User
%20Guides/Forms/All%20Documents.aspx.

1.4

Assumptions

The writer or author has already been identified using the Use It, Flag It, Fix It or Add It
(UFFA) process.

The BMC SD has categories defined for the application or process being documented.

-4-

2.0 KNOWLEDGE BASE DOCUMENT PROCESS STANDARDS


Use the process standards provided as a guideline.
1. Thoroughly search BMC SD to ensure what you are documenting does not already
exist.
2. Refer to section 4.0 Knowledge Base Document Content Standards as a guideline to
compose the content of the KB document.
3. Have a peer in your work group review your documentation for subject specific details
and correct formatting
4. Input the information into the BMC SD. For specific instructions on how to create the
KB document in BMC SD, please refer to the documentation: BMC KME: Use SDE
Incident Form to Search, Use and Create.
5. Promote the document to the appropriate Subject Matter Expert in your area. Refer to
the Master List for KB Tiger Team Members if you are not aware of whom your SME is
for your team. The Master List is located on the ITIL SharePoint site:
http://coawss3a.coacd.org/sites/ITIL/Knowledge/Lists/KM%20Tiger%20Team
%20Members/AllItems.aspx

Note: You are responsible for the content of the document including technical accuracy,
specific details, spelling, etc. The SME will perform a high level review.

6. The KB document will be reviewed by the SME and either returned for modifications or
additions or promoted to CTM Service Desk for Final Review and publication.

-5-

3.0 KNOWLEDGE BASE DOCUMENT GENERAL INFORMATION


Any information that is relevant to the applications and processes you support constitutes a KB
document. BMC SD is the central repository for ALL knowledge. ALL related information
must be either stored or referenced in BMC SD. See Sections 5.1 Master Lists and 5.2
Referencing/Linking or Attaching Documents for additional information. Knowledge Base
documents must but be entered in to BMC SD utilizing one of five templates described below.

3.1

Deciding What Template to Use

There are five types of KB documents in BMC SD.


important.

Finding the right template to use is

Error Message Use the Error Message template when you are documenting an
exact error message.

How to - Use the How totemplate when you are documenting How to do
something.

Problem/Solution Use the Problem/Solution template when you are documenting a


general problem that is not error specific.

Reference Use the Reference template when you are providing information about a
process or application.

Decision Tree Use the Decision Tree template when you are documenting a process
that requires different actions depending on the input.

-6-

4.0 KNOWLEDGE BASE DOCUMENT CONTENT STANDARDS


Use the Content Standards provided here as a guideline when creating a KB document.
Note: The word subject used in this section is defined as the application, process, etc. being
documented.

4.1

How to Title the Knowledge Base Document

Use the following naming convention when creating your KB document:


SUBJECT (In capital letters): Title of Knowledge Base Document
4.1.1

valid.
4.1.2

4.1.3

4.1.4

4.1.5

Example of Error Message Title:


AMANDA: Error Message - Run-time error '1177': The document name or path is not
Example of How toTitle:
VERSADEX: How to Create a User Account
Example of Problem/Solution:
LIMS: Problem - Bar Code Reader Not Working
Example of Reference:
GAP: Reference What is GAP?
Example of Decision Tree:
AMANDA: New User Account Process

-7-

4.2

Identify Knowledge Base Document User

The first line of text in the body of every knowledge base document must identify the intended
user. You must select one of the following:

4.2.1

For Resolution by the Service Desk

If the CTM Service Desk can resolve the issue add the statement:
If you are logged in to BMC SD Self Service, click Log Incident, complete the
Required Information, and then Submit the Incident.
OR
Contact the CTM Service Desk at 974-4357, staff has access to resolve.

4.2.2

For Resolution by specific WORKGROUP(S)

If the CTM Service Desk can NOT resolve the issue and it needs to be assigned to
another group add the statement:
If you are logged in to BMC SD Self Service, click Log Incident, complete the
Required Information, and then Submit the Incident.
OR
Contact the CTM Service Desk at 974-4357, so an Incident can be created and
assigned to WORKGROUP(S) name.

4.2.3

For Self Help Resolution

If this is intended for Self Help resolution, add the statement:


This KB document is intended as Self Help resolution for all users/customers:

4.2.4

For Reference by specific WORKGROUP(S)

If this is intended as a reference for a specific Work Group, add the statement:
No action required by CTM Service Desk. This document is intended as a Reference for
WORKGROUP(S) name.

4.2.5

For Self Help Reference

If this is intended as a reference for Self Help, add the statement:


This KB document is intended as Self Help reference for all users/customers:

-8-

4.3

Content to Include by Template Type

The fields and details required in a KB document vary by template. Please use the following
guidelines and standards when composing your document.

4.3.1

Error Message Template Content for Fields

Example: KME Document ID 508 (number is automatically generated)

-9-

Title:
Refer to the naming convention provided in 4.1 How to Title the Knowledge Base Document
Error:

State what the user is trying to do when receiving the error message

State the EXACT error message they are receiving and include a screenshot of the
error message if received

Self Help/Service Desk:

Identify your KB document user as described in 4.2 Identify Knowledge Base


Document User

If this is intended as a Self Help Resolution, list the steps that must be performed by
the user in detail.

Root Cause:
List the root cause of the error if known
Internal Workaround/Fix:

Enter any critical assumptions to perform the steps (i.e., Must have Administrator
Rights)

If this is intended as Internal Resolution, list the steps that must be performed in detail
or link to another document with the instructions.

Keywords:
Keywords for searching and the name of the WORKGROUP from BMC SD (i.e.
AMANDA_SUPP)
Content Author:
Name of KB creator
Format Author:
Name of KB format and editor

- 10 -

4.3.2

How to

Example: KME Document ID 1043 (number is automatically generated)

- 11 -

Title:
Refer to the naming convention provided in 4.1 How to Title the Knowledge Base Document
Question:

Enter How do <task name>?

Self Help/Service Desk:

Identify your KB document user as described in 4.2 Identify Knowledge Base


Document User

If this is intended as a Self Help Resolution, list the steps that must be performed by
the in detail.

Internal Answer:

Enter any critical assumptions to perform the steps (i.e., Must have Administrator
Rights)

If this is intended as Internal Resolution, list the steps that must be performed in detail
or link to another document with the instructions.

Keywords:
Keywords for searching and the name of the WORKGROUP from BMC SD (i.e.
AMANDA_SUPP)
Content Author:
Name of KB creator
Format Author:
Name of KB format and editor

- 12 -

4.3.3

Problem/Solution

Example: KME Document ID 1460 (number is automatically generated)

- 13 -

Title:
Refer to the naming convention provided in 4.1 How to Title the Knowledge Base Document
Problem:

Enter the general description of the problem

Self Help/Service Desk:

Identify your KB document user as described in 4.2 Identify Knowledge Base


Document User

If this is intended as a Self Help Solution, list the steps that must be performed by the
user in detail.

Internal Solution:

Enter any critical assumptions to perform the steps (i.e., Must have Administrator
Rights)

If this is intended as Internal Solution, list the steps that must be performed in detail or
link to another document with the instructions.

Keywords:
Keywords for searching and the name of the WORKGROUP from BMC SD (i.e.
AMANDA_SUPP)
Content Author:
Name of KB creator
Format Author:
Name of KB format and editor

- 14 -

4.3.4

Reference

Example: KME Document ID 1366 (number is automatically generated)

- 15 -

Title:
Refer to the naming convention provided in 4.1 How to Title the Knowledge Base Document
Self Help / Service Desk:

Identify your KB document user as described in 4.2 Identify Knowledge Base


Document User

If this is intended as a Self Help Reference, document the information necessary for
the user.

Internal Reference:

If this is intended as Internal Reference, document the information necessary for the
internal staff.

Keywords:
Keywords for searching and the name of the WORKGROUP from BMC SD (i.e.
AMANDA_SUPP)
Content Author:
Name of KB creator
Format Author:
Name of KB format and editor

- 16 -

4.3.5

Decision Tree USING THIS TEMPLATE IS NOT RECOMMENDED

Example: Include Document ID 218 (number is automatically generated)


Title:
Refer to the naming convention provided in 4.1 How to Title the Knowledge Base Document
Self Help / Service Desk:

Identify your KB document user as described in 4.2 Identify Knowledge Base


Document User

Enter any critical assumptions (i.e., Must have Administrator Rights) as questions in the
decision tree as appropriate

Internal Decision Tree:

Enter any critical assumptions (i.e., Must have Administrator Rights) as questions in the
decision tree as appropriate

- 17 -

4.4

Review of KB Documents

KB Document will need to be reviewed / modified for various reasons.

4.4.1

Maintenance Review

All KB Documents will need to be reviewed at a minimum every 18 months to ensure they are
up-to-date.

4.4.2

Flagged KB Document

A KB document may be flagged for review by another user other than the owner of the
document if it does not sufficiently explain a process, is out-of-date or contains any other
inconsistency.

4.4.3

Proactive Review

The owner of the KB document is aware of a needed update and proactively modifies the
document. A work group may decide to establish a more frequent review cycle than the
standard Maintenance Review depending on their business needs.

- 18 -

5.0 OTHER BEST PRACTICES


5.1

Master Lists

Several documents may include the same information. If the information is embedded in the
documents and there is a change then multiple documents need to be modified. The purpose
of a Master List is to centralize this information by referencing the information rather than
embedding it in the documents. This allows the information to be updated in one place and
the update reflected in all documents.

5.1.1

Storage Location of Master Lists

Determining where to store Master Lists depends on the intended audience and the access
level.

If it is intended for your work group only, the Master List should be stored on your
workgroup SharePoint site.

If it is intended for Self Help, the Master List should be stored on the Service Desk
SharePoint site: http://coawss3a.coacd.org/sites/CTM/IMD/HD/KMESH/Forms/AllItems.aspx.

5.1.2

Examples of Master Lists

Passwords: Secure list of systems passwords

Vendor Contact Information: List of vendors contact information

Customer List: List of customers supported

Standards List: List of standards within your workgroup

Tools List: List of tools used within your workgroup for development or monitoring

Applications List: List of applications developed or supported

Computer Server Names and IP Addresses: Secure list of server names or IP


addresses

Network Diagrams: Secure list of network diagrams for your application

Data Flow Diagrams:

Power Users or SME contacts: List of Power Users for your application

Benefits List: List of benefits for services or activities being performed

Cost Lists: List of items and costs that are typical i.e., vmware, licensing, hardware,
software

- 19 -

5.2

Referencing/Linking and Attaching Documents

Avoid rewriting vendor manuals or lengthy documents developed for your workgroup. Instead,
create a KB document and attach or reference/link the information.
For instructions on how to attach or reference/link the desired information, refer to the
documentation: http://coamagic/helpdesk/default.asp - then click the Knowledge Tools tab
and search for KME Doc ID: 1652.

5.2.1

Storage Location of Attachments

Determining where to store attachments depends on the intended audience and the access
level.

If it is intended for your work group only, the attachment should be stored on your
workgroup SharePoint site in the applicable library set-up with staff rights.

If it is intended for CTM only, the attachment should be stored on your workgroup
SharePoint site in the applicable document library set-up with read rights to CTM Employees.

If it is intended for Self Help, the attachment should be stored on the Service Desk
SharePoint site: http://coawss3a.coacd.org/sites/CTM/IMD/HD/KMESH/Forms/AllItems.aspx
For a visual understanding of Storage Location of Attachments, refer to the documentation:
http://coawss3a.coacd.org/sites/ITIL/Knowledge/Knowledge%20Management%20User
%20Guides/KME%20Standards/KM%20Attachments.pdf

5.2.2

Examples of Attachments
Training Manuals
Installation Guides
Lengthy documents
Detailed instructions with screenshots

- 20 -