KB User's Guide - Overview of Fields in Document editor

This document gives an overview of each field on the document creating/editing form. The Title, Keywords, Summary and Body fields are required.

Template | Title | UrlSlug | Search Priority | Page Header and Page Footer | Keywords | Summary | Body | Attachment | Show Other Notes | InternalNote | MyGroupNote | See Also | Up, Previous, Next | Up | Previous | Next | Type | Topics | Audiences | WriteAccess | ReadAccess | SiteAccess | CampusAccess | Relevance | Status | Activation | Expiration | Additional Fields | Change Summary | Owner | Notification | FeedbackTo | MiscOptions | JavaScript/CSS | Show comments and events

Template

In a New Document, selecting a specific item from the dropdown list in the Template field allows you to populate many fields like  Title, Keyword, Summary, InternalNote and JavaScript/CSS, to name a few, in a pre-defined template. If "No templates defined or available" is your only option in that field, and you'd like to create a template, please see KB User's Guide - Documents Tab - Template Creation via a New Document Set to "Template" Type.

Title

A well-written Title tells the reader what a document is all about, and is critical in providing document clarity. For example, an effective Title could begin with the name of the product or service, followed by the subject of the document (For example "Internet Explorer 12 (Win) - Clearing Cache and Cookies"). It is important to make the title clear and concise. The maximum length of the title is 200 characters. Title is a required field as designated by the asterisk.

UrlSlug

The UrlSlug can be generated from the document title and be further altered manually. The human readable, lowercase keywords (separated by dashes) will then appear at the end of the url to your kb document. The slug may be optimized for brevity or for consumption by search engines. Please refer to KB User's Guide - Documents Tab - UrlSlug Field to learn more about this feature.

Keywords

Keywords determine whether or not the document will be found in KnowledgeBase (KB) Live Site searches. When a user submits a search query, the KB searches all documents that contain those Keywords entered, while ignoring case. Keywords should include product or service names, key concepts, error codes, misspellings, and other words and phrases you might expect the one to use to find the document. Keywords may be separated by spaces or commas. Phrases may be separated by quotations or parentheses. Please know that the individual terms in a phrase will all be searched as a group and searched individually (e.g. word by word). This is very useful, especially if some of the words in the phrase are very common. There is no need to include document title words in the keyword list as they are automatically included. The Keywords field is a required field as designated by the asterisk.

Search Priority

The Search priority dropdown list contains a number of options:





Documents flagged with Exclude from search, however, can be viewed by their document ID number in the URL or by their document ID number in the search box.


The Exclude from search option can be particularly useful for short documents/texts (e.g., disclaimers, warnings, and credits) that are meant to be included in other KB documents.


Page Header and Page Footer



The Page header and Page footer links allow authors to apply predefined headers and footers to their documents using a dropdown list. Users with publish rights can also define new headers and footers or edit existing options using these links. For instructions on how to apply, define, and edit headers and footers, please see: KB User's Guide - Documents Tab - Define and Apply Document Headers and Footers

Summary

A good summary succinctly indicates the purpose and/or the main point or issue of the entire document so that a user may glance at the opening paragraph and quickly see what is available in that document. The summary is meant to be a basic description of the document. As a result, you cannot use the WYSIWYG editor to format text in the summary field. You may, however, change the appearance of content in the summary using HTML code. We encourage you to leave the Summary field as simple as possible. The Summary field can optionally be displayed when browsing search results in the KB, which is the main reason we encourage a simple, succinct Summary. The Summary field is a required field as designated by the asterisk.

Body

The Body field contains the bulk of the information in a KB document. The Body field can be edited using either the HTML or the WYSIWYG editor (Design) mode.



Users may select either the HTML or WYSIWYG editor as their default editor by going to:



Users may toggle between HTML mode and WYSIWYG (Design) mode by clicking the HTML or Design links at the bottom left of the Body text area.

The WYSIWYG editor, in addition to having many of the commonly used tools, includes extensive CSS capability (great for creating text banners, etc.), dynamic table creation (adding/removing rows and columns on the fly), image alignment (great for having text wrap-around), and full screen mode.

While creating/editing a document, you can easily switch between Design mode, HTML mode, and Preview mode. The editor in HTML mode contains quick code buttons (except definition list) and also has a full screen toggle.

If you prefer HTML mode to design mode most of the time, you may switch your default editor mode to HTML source mode:

If you prefer an HTML editor without quick buttons, you may switch your default editor mode to HTML ONLY without Quick Code Buttons:

The WYSIWYG editor has been tested in current versions of IE, Firefox, Chrome and Safari. Different browsers handle spacing and styling differently; but for the most part, everything works well.

To stay true to the HTML syntactical standards, the nine custom tags have been implemented as follows:


Attachment

Use the Attachment tool to add resource files to your document. This can be used to add not only images (.PNG, .JPG, and .GIF) to your document, but other resource files as well (e.g. .PDF, .PPTX, .DOCX, etc.). For more information about adding attachments to your document, see KB User's Guide - Documents Tab - Uploading Images and Other Attachments.


Show Other Notes

If you expand the Other Notes section by clicking on the (plus) icon, you will be able to specifically use an InternalNote and/or a MyGroupNote.


InternalNote

You can use InternalNote to enter information visible only to your internal staff. You may publish the document to both the internal and external sites; the content in the InternalNote is only accessible via the internal site. HTML coding is necessary for formatting the InternalNote field. You can also accomplish this by adding your content to the Body of the document and wrapping with the IntSite tag as described above.

The image below shows the expanded InternalNote field. To collapse, just click on the upper left corner. To expand the field further (in the event you have a long InternalNote to edit), click and drag the lower right corner to the desired height.


MyGroupNote

The MyGroupNote field allows KB groups to add information to documents that are owned by other KB groups. Information entered in MyGroupNote will be visible to your own group's internal and/or external sites only. This functions somewhat like the InternalNote field, which is visible to internal KB site(s) only. The difference is that the MyGroupNote field is group-specific; for a given document shared across multiple groups. Each of these sharing groups will have its very own MyGroupNote field.

MyGroupNote will be the only editable field available to groups that are sharing, but do not own, the document. The group that owns the document will be able to edit the MyGroupNote field as well as all other available fields. Text in the MyGroupNote field is only visible to the group that was editing this field in KB Admin Tools. You have the option to have the text appear either Above Summary or Under Body (default), depending on which selection you choose in the dropdown list.


The MyGroupNote field allows the author and/or owning group to embed information suitable for its own intended audience. It also allows other groups sharing the same document to append notes that are suitable for their respective audiences even when the sharing groups do not have write access to edit the main content of the document.

For instance, let's say the DoIT Help Desk and Computer Aided Engineering (CAE) share a core set of VPN documents. At the end of these documents, the DoIT Help Desk users can be instructed via MyGroupNote to contact the DoIT Help Desk for further assistance, while the CAE users can be instructed via MyGroupNote to contact local CAE support staff.

Likewise,University of Chicago (UoC) and UW-Madison, while sharing virus removal documentation, can use MyGroupNote and have UoC's contact information show up when these pages are viewed via UoC's KB, and UW-Madison's contact information show up when the documentation is viewed via UW-Madison's KB sites.

To facilitate the use of MyGroupNote, all group-specific notes are displayed when reviewing a document in the KB Admin Tools. Each of these notes is marked with the group name for which the note is visible. Review  KB User's Guide - Documents Tab - Dynamic Content Replacement  to learn how to use this field for dynamic replacement of content.

SeeAlso

Use the SeeAlso field to link to other documents related to your document. Enter the document ID number with related content in this field. When displaying the document, the SeeAlso document ID numbers will be replaced with linked document titles. You may enter any document ID numbers, but the links are visible only when the linked documents are active. SeeAlso should only contain valid, comma delimited document ID numbers and ID numbers with bookmarked anchors appended (such as 4418#ldap).

Auto Redirect for "Obsolete" Documents

When you open a document that has been deactivated (usually by document ID number or hyperlink), the system will check to see if the "obsolete" document has any SeeAlso value(s). If a SeeAlso value exists, the system takes the first or sometimes the only document id number in the SeeAlso field, verifies that document to be active (to prevent potential infinite loops) and then redirects you to the active (superseding) document. Please see KB User's Guide - Document Tab - Redirect a document via the See Also field  for details.

Up, Previous, Next

The Up, Previous, Next fields can be used to link documents in a logical sequential order. This may be useful when creating training documents or when creating longer documents that need to be broken up into separate pages.

If a user does not have access to a document that is included in an Up, Previous, Next link, that link will not be displayed for that user.

If any or all of the Up, Previous, Next fields are left blank, the links and labels will not appear when the document is displayed.

Up

Use the Up field to link back to the first document in the series of documents related to your document (possibly the Table of Contents document). Enter the document ID number that is considered the first document in this series of documents in the Up field. The first document in a series may or may not have a document listed in the Up field. The Up field can be left blank.

Previous

Use the Previous field to link to another document related to your document. Enter the document ID number that precedes your document in the Previous field. The first document in a series may or may not have a document listed in the Up field. The Previous field can be left blank.

Next

Use the Next field to link to another document related to your document. Enter the ID number of the document that follows your document in the Next field. The last document in a series may or may not have a document listed in the Next field. The Next field can be left blank.


Example usage of Up, Previous, Next function

Note, as shown in the diagram and screen shots below, that Up and Previous will be left blank for the first document. The Up and Previous labels and links will not appear when the first document is displayed. On the last document the Next field will be left blank and the Next label and link will not appear when the last document is displayed.


upprevnextdia.png


KB Admin Tools Configuration

In KB Admin Tools > Document Editor the Up, Previous, and Next fields should be configured as shown below to connect a series of four documents with the document IDs of 1, 2, 3, and 4:

To see an example of Up, Previous, and Next in action, take a look at this document: KB User's Guide - Documents Tab - Demo - Up, Previous, Next - Page One.


Type

Selecting a Type from the dropdown list determines whether you are creating a document, a template or a glossary item.


Topics

The Topic field is used to logically group documents in your site. All documents should have a topic/topics chosen that are most relevant to the document content. It is important to set this field correctly as topic specific searches depend on this value being accurate. Any KB document can be categorized under more than one topic.


topicsedit.png


On the document edit form, the Topics field accepts multiple values. The field displays the highest most topic level in the hierarchy. Click the (plus) button to expand the view to show any available sub-topics. Multiple topics can be selected for one document. Topics may be selected from any level in the hierarchy.


topicsedithier.png


If the document is shared out to other groups, other groups may assign multiple topics to that document within their own KB environments.

A document with multiple topic assignments will show up under different Topics while users are searching for it (even within one KB site).

Groups that do not want to use multiple topics selection can simply check one Topic or not check a Topic for each document.

Audiences

The Audiences field provides a way to delineate a group of documents for a specific Audience working much like Topics. While there are 8 fixed Audiences, custom Audiences may also be created. There are two ways to display documents for your group's Audiences on your KB Live site(s): you may create a Side Module or enable a dropdown list. For more information, please see  KB User's Guide - Documents Tab - Audiences.

WriteAccess

The WriteAccess field specifies who, specifically, which group, has rights to modify the content of the document. There are at least four fixed options:



If the four WriteAccess options do not suffice, KB admins can define User Access Groups, which will in show up in the WriteAccess groups section.



When a user without WriteAccess attempts to edit the document, almost all fields will be grayed out. The document owner, however, will always be able to edit the document even if he or she is not on the User Access list.


ReadAccess


The ReadAccess field specifies who, specifically which group, has rights to read the content of the document. The ReadAccess field allows document authors to limit who has access to a specific document by indicating which ReadAccess groups have access to the document. Any user not in the selected ReadAccess group will not have access to the document.


When editing a new document or if no user access groups have been selected, the document editor template will display "No user groups selected" and a link "Show all user groups" as shown in the screen shot below.




Click the Show all ReadAccess groups link to display available ReadAccess groups.




Once a document is restricted to one or more ReadAccess groups, it is only accessible to users on those lists, even within the KB Admin Tools environment. If a user is on the ReadAccess group, the document will display normally. If a user is not, a message will display indicating that the document is restricted to a pre-defined User Access Group, and offers the option of contacting the document owner to gain access.


ReadAccess restriction should not be used for documents that are meant for public consumption. It works with documents published to internal KB sites only. When an associated ReadAccess group is deleted, the restriction on the document will cease to exist.


If no ReadAccess groups are selected then a document's ReadAccess is strictly determined by SiteAccess - a document published to an internal site is accessible to relevant KB group members, and an external document is accessible to the world.


If the document is published to an external site it may become available to the world (ignoring internal read access restrictions).


SiteAccess

The Site Access field allows you to publish a document to one or multiple KB websites. For a list of all active KB sites, go to the SitePref tab and select Group Spaces link on the left. See this section; "Columns on the Managing Group Relationships Table" for instructions on adding and removing KB sites from your SiteAccess list.




Clicking on the plus.png (plus) sign next to Show Other Site Access will display a list of other KB sites with whom you may share documents. From here, you will also see which KB sites have the Trust Activation enabled.


CampusAccess

The CampusAccess field allows individual documents to be put behind a general campus login and therefore not accessible to the general public.


Documents that are behind a general campus login are "discoverable" via external (and internal) site(s) since the title(s) will appear in search results (with text indicating campus login required). When the user clicks on the link, the user will be prompted to log in (if the user isn't logged in already) before the document content is presented to the user. Since the title is no longer hidden, authors will need to be mindful to not to reveal too much in the title if a document is restricted to campus authorized users only.


campus_access_three_radio_button_selection



Relevance

The four options in the Relevance field allows users to rate the relevancy of their document thereby making it searchable within group(s), your institution only or by all institutions. This feature is also referred to as implicit sharing.





Status

The Status field indicates document status in the document creation, review, and publication cycle. There are four possible values:

 


Activation

Use this field to set a date for activation. This can be useful for preparing documentation in advance of a product or service rollout. For deferred activation date time to take effect, the document status must be set to Active. In other words, if the document is not active on the activation date the document will not be available. Clicking on the Pick activation time link will lead you to a pop up calendar. Clicking on any date on this calendar will auto-populate the Activation field. For details on the Future Activation feature, please see future KB User's Guide - Documents - Future Activation 



Expiration

Use this field to specify a date when the document will expire. Once a document expires, it will no longer be available for searching or viewing via any KB web sites. It will still be available for searching in the KB Admin Tools as an expired document. For more info see How to Set Document Expiration Date. Clicking on the Pick activation time link will lead you to a pop up calendar. Clicking on any date on this calendar will auto-populate the Activation field. Clicking on the Never link sets the Expiration date to 3000-01-01 00:00:00...not exactly never, but close.


Expiration.png


Additional Fields

If you expand the Additional Fields section by clicking on the icon, you will have some additional options available.


Change Summary and Minor Change

The Change Summary field will appear when updating an existing document. It allows the document editor to make note of changes being made during this revision. The "Minor change" checkbox option does three things:


Owner

The Owner field indicates the name of the person who has authored or provided the original content. Questions about documents and review requests are directed to the document owner.


Notification

The Notification field allows you to notify the document owner, or owner group (My group), or groups sharing the document (Sharing groups) when you create, update, activate, or inactivate the document.

FeedbackTo

The FeedbackTo field allows you to specify at the document level where user feedback should be routed. This is implemented in addition to existing group feedback option, which typically routes user feedback to document owner and/or group email address.

'FeedbackTo' is an optional field and should contain valid, comma delimited email addresses only. There is no need for a comma if there is only one email address. The document creating/editing form does not validate the syntax of proper email addresses, but it does remove duplicate addresses and extra commas.


MiscOptions

The following options are available under the MiscOptions section: Blog, No reminder, No keyword suggestion, No blog, No comment, and HTML only mode.



JavaScript/CSS

Placing code in this field allows the creation of page-specific JavaScript code and CSS. Authors will no longer need to manage JavaScript code nor CSS with the actual content (Body field). To locate the JavaScript/CSS input box, expand Additional Fields at the bottom of the document editor.

Because this field allows the input of both JavaScript and CSS, code entered here should be wrapped in <script> </script> tags or <style> </style> tags, respectively.

You may also use this field to call external JavaScript or CSS files that you have uploaded to your document's attachment folder or group's Shared Attachment folder, e.g.: