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.
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.
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 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.
The Search priority dropdown list 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 searchis 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.
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
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.
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.
- For more information on the HTML document editor buttons see this document Guide to Document Editor Buttons.
- For more information about the WYSIWYG document editor buttons see this Guide to WYSIWYG Document Editor buttons.
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="kb-class-internal-site">...</span>
- ExtSite<span class="kb-class-external-site">...</span>
- OwnerSite<span class="kb-class-owner-group-site"></span>
- OwnerInstitution: <span class="kb-class-owner-inst-site"></span>
- LinkNews: <a class="linknews">...</a>
- IncludeNews: <a class="includenews">...</a>
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.
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.
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.
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.
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 in the status of Active. The SeeAlso field should only contain valid, comma delimited Document ID numbers and ID numbers with bookmarked anchors appended (such as 4418#ldap). You may also use a single space between each Document ID number.
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.
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.
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.
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.
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.
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
- Second Page
- Third Page
- Fourth Page (Last)
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.
Selecting a Type from the dropdown list determines whether you are creating a document, a template or a glossary item.
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.
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.
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.
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.
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.
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).
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) 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.
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.
- 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
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.
The Status field indicates document status in the document creation, review, and publication cycle. There are four possible values:
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
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.
If you expand the Additional Fields section by clicking on the icon, you will have some additional options available.
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".
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.
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.
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.
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 [Link for document 19224 is unavailable at this time.] for more information.
<script> </script> tags or
<style> </style> tags, respectively.