In this document:

• Background
• Title
• Keywords
• Summary

Background

Before a document is ready for your users to see, it is important to add three of the four required fields to provide good search context and a general overview to what the document's content will contain.

Title

As you saw in the document KB Author Training - Creating a New Document, the title field must be filled out in order to save a new KB document. For users searching the KnowledgeBase, the title is the chief source of information about the contents of your document:

Considerations

• The maximum length of the title is 200 characters.
• The title field does not accept formatting (XHTML) and defaults to the Header 2 (H2) sized font.
• Words in the title will automatically be treated as keywords (see below).

Keywords

Keywords do not appear in the text of the document itself. Instead they establish which search terms will return your document when a user submits a search query via the KB search.

The image below shows the Search field in the Office of the Registrar live site. In the search field is the word 'pear'. Upon clicking on the Search button, all documents with 'pear' in the title or keywords fields will appear. In this particular case, since there are zero documents with the word, "pear", the words "No matches" appear above the search field. There is also a link above the search field called "Suggest a document" which leads to a feedback form.



Generally speaking, keywords should include:

• product or service names
• major concepts
• acronyms
• nicknames
• beta version names
• error codes
• misspellings
• formerly used names or references
• action phrases and variations of the action verb
• other words/phrases you might expect users to search for

In coming up with keywords, try to anticipate which terms your users will associate with your documents.

Considerations

• Keywords may be separated by commas or spaces.
• Keywords are not case-sensitive (i.e. if you specify 'pear' as a keyword, your document will appear whether a user searches for 'pear' or 'Pear').
• Words in the document title are automatically included as keywords.
• Your KB space administrator can define Default Keywords for your site, which you can insert into the Keywords field using the Show default keywords. For more information about Default Keywords, please refer to KB User's Guide - Documents Tab - Default Keywords.

Summary

The Summary field should provide a succinct description of the contents and/or the purpose of the document. Users should be able to quickly scan the summary to determine if this particular document is what they are looking for.

Considerations

• Depending on the way your KB site is configured, the text you enter in the Summary field may appear in KB search results (another reason to keep it as simple as possible).
• Although it is possible to alter the appearance of content in the summary using XHTML code, we encourage you to keep the summary as simple as possible.

Exercises

Title

In the previous exercises, you created and edited a document with a title in the following format: '[Your Name]'s First KB Document'. However, as stated in the background section of this document, the title is often the main source of information about your document to users searching the KB. Ideally a document's title should contain information about its contents. Update your document's title to be more descriptive using the following steps:

1. Log into the KB Admin Tools.

   Note: If your institution is not using Shibboleth, go to the Active Directory Login.

2. Click on the Documents tab and locate your KB document.

3. Open the document for editing and locate the Title field.

4. Rename the document something along the lines of: '[Your Name]'s - KB Author Training - Demonstrating KB Features'. This title tells potential users that your document is not a live KB doc; it also describes the function of the document.

5. Click Preview to see the new title displayed on the document. If you are satisfied with the change, click the Save Change button. If not, go back to the Title field and make any necessary adjustments.

Keywords

In KB Author Training - Creating a New Document, you assigned your document a list of arbitrary keywords. Although you got to see how the keywords field worked, the keywords themselves had no relation to the contents of the document. Since keywords determine whether your document will be found when KB users perform searches, it is especially important that they relate to the main concepts or topics covered in the document. Update your document's keywords to be more descriptive using the following steps:

1. If you are not already logged in, log into the KB Admin Tools.

   Note: If your institution is not using Shibboleth, go to the Active Directory Login.

2. Click on the Documents tab and locate your KB document.

3. Open the document for editing and locate the Keywords field.

4. Add keywords that a user searching for your document might type into the search window, such as 'example, demo, KB Admin, editor, body, keywords, summary, field, fields'. Remember that keywords must be separated either by commas or by spaces.

5. If you are satisfied with the new keywords, click Save Change. If not, go back to the Keywords field and make any necessary adjustments.

6. Once you are done making and saving changes, scroll down to the bottom of the document editor, make sure that the document status is In Progress, and click on the Submit.

7. To see the new keywords in action, click the In Progress link on the left-hand menu of the Documents tab. In the Search Term field under the Active Documents heading, enter one of the keywords you just saved (e.g. 'demo') and click on the Go button. Your document should appear in the list that shows up. If it does not, go back to the document editor and ensure that the keyword you searched by is saved in the document's Keywords field.

Summary

As with the above sections, the summary should contain information about the contents of the document. Unlike the Title and Keyword fields, the summary can and should contain complete sentences (see the summary at the top of this training document for an example). The recommended length for a document summary is no more than several sentences. Update your document's keywords to be more descriptive using the following steps:

1. If you are not already logged in, log into the KB Admin Tools.

   Note: If your institution is not using Shibboleth, go to the Active Directory Login.

2. Click on the Documents tab and locate your KB document.

3. Open the document for editing and locate the Summary field.

4. Enter a summary that reflects the contents of the document, such as 'This document was created as part of a KB author training exercise. It contains several examples of the KB document editor's functions'.

5. Click Preview to see the new title displayed on the document. If you are satisfied with the change, click Save Change. If not, go back to the Summary field and make any necessary adjustments.

6. After editing the Title, Keywords, and Summary in these exercises, you should end up with a document that looks like this. If your document does not resemble the example, try working through the steps above until you locate the discrepancy.