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

In a New Document, selecting a specific item from the drop down 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 drop down menu contains a number of options:


  • If Top priority is selected when the document is activated. The document will appear before all documents with lower (High, Normal, and Low) search priority levels in KB search results.
  • When Top priority documents appear in the Live Site search results, they are accompanied by the following indicator , of four gold asterisks. If you hover your mouse over the asterisks, you will see the Top priority label.
  • If High priority is selected when the document is activated, the document will appear in KB search results before all documents with lower (Normal and Low) search priority levels and follow all documents with higher (Top) levels.
  • When a High priority document appears in the Live Site search results, they are accompanied by the following indicator in the KB search results, of three gold asterisks. If you hover your mouse over the asterisks, you will see the High priority label.
  • If Normal priority is selected when the document is activated. The document will appear before all documents with lower (Low) search priority levels and follow all documents with higher (High and Top) levels. By default, all documents are set to Normal priority.
  • If Low priority is selected when the document is activated, the document will follow all documents with higher (Normal, High, and Top) search priority levels.
  • If Exclude from search is selected when the document is activated, that document will not be included in any of the following search results:
    • User search results
    • Top Documents of the Week
    • Most Recently Updated Documents

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 drop-down menu. 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 - How to Define and Apply Headers and Footers in a Document

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:

  • KB Admin Tools > Home > UserProfile >Edit link >Editor mode radio buttons.

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:

  • KB Admin Tools > Home >UserProfile box > Edit link >Editor mode section > HTML with Quick Code Buttons radio button.

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

  • KB Admin Tools > Home >UserProfile box > Edit link >Editor mode section > HTML ONLY without Quick Code Buttonsradio button.>

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:

  • KbLink:<a href=" page.php?id=xxxxxx">...</a>
  • ToTop:<div class="to-kb-doc-top-anchor">...</div>
  • LinkDoc: <a class="linkdoc">...</a>.
  • IncludeDoc: <a class="includedoc">...</a>
  • LinkTopic: <a class="linktopic">...</a>
  • IntSite: <span class="internal">...</span>
  • ExtSite<span class="external">...</span>
  • OwnerSite<span class="ownersite"></span>
  • OwnerInstitution: <span class="ownerinstitution"></span>
  • LinkNews: <a class="linknews">...</a>
  • IncludeNews: <a class="includenews">...</a>

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 menu.


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.

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 - See Also Redirection 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:

  • First Page

    upprevnextdoc1.png

  • Second Page

    upprevnextdoc2.png

  • Third Page

    upprevnextdoc3.png

  • Fourth Page (Last)

    upprevnextdoc4.png

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 drop down menu 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 menu. 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:

  • Owner: Allows only the owner of the document to make edits.
  • Owner group admins: Allows all admins of the owner group to make edits; this includes all authors who have been granted both GroupDocs (gDocs) rights and Publish rights, regardless of whether they have access to all tabs in the Admin Tools.
  • Owner group: Allows all members of the owner group to make edits: this includes all authors who have been granted both GroupDocs (gDocs) rights and Publish rights, regardless of whether they have access to all tabs in the Admin Tools,
  • Sharing groups: Allows any member of any group that has been granted sharing permission in the Group Relations table to make edits. This affects transferring document ownership from one group to another. This includes all authors who have been granted both GroupDocs (gDocs) rights and Publish rights, regardless of whether they have access to all tabs in the Admin Tools,

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.

  • Note: if no ReadAccess groups have been created for this KB group, none will appear in this section. For more info about creating ReadAccess group, review this document on User Access Groups

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

  • Defer to Site Access: Document and attachment access will be determined by KB sites selected in the Site Access and Other Sites fields.
  • Ext/Internal with campus login: Document and attachment access will be limited to campus authenticated users. Document title is exposed to external site users, but document content access will require users to log in. For this option to work as intended, a group space's "Internal" SiteAccess must be also selected if its "External" SiteAccess is selected.
  • Internal for all campus users: Document and attachment access will be limited to authorized internal users and ANY campus users with valid login credentials. For this option to work as intended, only "Internal" SiteAccess should be selected

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.

  • My Group/sharing groups: Your document is only searchable within your own KB. Each document is defaulted to this setting.
  • My Campus: Your document is searchable by your Campus and other groups with whom you collaborate.
  • My University System: Your document is searchable by anyone in your University System. The external site box must be checked in the SiteAccess section of your document.
  • Universal: Your document is searchable by anyone in any institution. The external box must be checked in the SiteAccess section of your document.

Status

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

  • In Progress: A document with an In Progress status is actively being edited. It may be a new document that has never been published or a previously published document that requires edits.
  • In Review: An 'In Review' status indicates edits are complete and you are ready for the document to be reviewed and published. Use this status to have new documents activated, to have updated documents activated, or after adding notes to indicate action is necessary.
  • Active: Documents are set to Active once they have been properly reviewed and revised. Once a document is Active, it is published and available on the live, KB site
  • Inactive: Documents are set to Inactive once they have become obsolete.
  • Note: groups may use these options differently. For example, some groups may not use In Review at all.

    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.

    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:

    • Bypasses the review and re-activation on the part of sharing groups which have previously approved the document for their sites. In other words, if  "Minor change" is checked, then when changes to that document are activated the changes will automatically be pushed out to any groups sharing that document. The sharing group will not need to approve the changes.
    • Excludes the document from the "Most Recently Updated Documents" list.
    • Prevents an email notification from going out to users who have subscribed to "Notify me when this page changes".

    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.


    • Blog - Enables the blogging option for the published document.
    • No reminder - Disables review reminders for documents that don't need to be reviewed (eg. meeting minutes).
    • No keyword suggestion - Disables the "Suggest keywords" button in the published document.
    • No comment - Disables the "Comment" button in the published document.
    • HTML only mode - Locks the editor for a doc with java scripting or other things that get weird in the WYSIWYG editor. A document with HTML only set can only be opened with the HTML editor.
    • Activation PIN Required - Allows an extra level of security by requiring PIN be provided to submit a document for publication. Please see Document 19224 is unavailable at this time. for more information.

    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.

    Show comments and events

    The comments and events section has two modes: show and hide. It defaults to hide mode. To show comments and events, click on the (plus) sign to the left of Show comments and events. Show comments and events becomes Hide comments and events and reveals userID, date, timestamp and specific actions that occurred on that document. Examples are: Created, Status changes such as In Review, In Progress, Activated, Deactivated and Deleted. Other changes that are indicated here are dates Review reminders are sent and indications of Batch Updates and reason Batch Updates were made.




    Keywords:kb knowledge base knowledgebase drafts tab documents draft document field button buttons validation tools document editor creation expiration see also redirect obsolete mygroupnote my group note notes UserAccess User Access campus No campus level restriction Owner campus authorized users only Sharing campuses authorized users only no reminder no blog disable comments HTML only title keywords summary body seealso up prev previous next includedoc linkdoc kblink LinkTopic documents tab relevant relevance implicit sharing to top form Template Title Keywords Search Priority Page Header and Page Footer Summary Body Attachment Other Notes InternalNote MyGroupNote See Also Up, Previous, Next Up Previous Next Type Topics Audience Audiences WriteAccess ReadAccess SiteAccess Relevance Status Activation Expiration Additional Fields Change Summary Owner CampusAccess Relevance status activation expiration additional fields change summary owner feedback to Notification FeedbackTo MiscOptions JavaScript/CSS required fields show comments and events url slug UrlSlug   Doc ID:5238
    Owner:Teresa A.Group:KB User's Guide
    Created:2007-01-03 19:00 CDTUpdated:2016-08-29 16:33 CDT
    Sites:KB Demo, KB Demo - Child Demo, KB User's Guide
    Feedback:  3   1