Skip to content

User Guide

This guide explains how to use the Knowledge module's features for day-to-day knowledge management tasks.

Table of Contents

Getting Started

Understanding Knowledge Management

The Knowledge module helps organizations connect support incidents (like tickets, issues, or cases) with knowledge articles (like help documents, FAQs, or solutions).

Key benefits: - Find relevant documentation quickly - Track which articles are most useful - Identify documentation gaps - Measure knowledge management effectiveness - Track personal growth in knowledge management skills

Your Role in Knowledge Management

Depending on your permissions, you may be:

  • Knowledge User: Can view knowledge links and articles
  • Knowledge Candidate: Learning to create and link knowledge
  • Knowledge Contributor: Regularly creating and linking knowledge
  • Knowledge Publisher: Approving and publishing knowledge content
  • Knowledge Manager: Overseeing the entire knowledge system

Check with your administrator if you're unsure of your role.

Accessing Knowledge Features

Main menu locations: - Content > Knowledge: View and manage knowledge links - Reports > Knowledge: Access reports and analytics - Structure > Knowledge: Configure knowledge types (admin only) - Your profile: View your competency status

Knowledge links connect incidents to articles. For example, linking a support ticket to the help article that resolved it.

On Content Pages

When viewing an article or incident with knowledge field:

  1. Scroll to the knowledge section (usually near the bottom)
  2. You'll see:
  3. List of linked incidents or articles
  4. Statistics (how many links, when created)
  5. Links to view full details

In Knowledge Lists

View all knowledge links:

  1. Navigate to Content > Knowledge (/admin/content/knowledge)
  2. See list of all knowledge links
  3. Filter by:
  4. Knowledge type
  5. Author
  6. Date range
  7. Incident or article
  8. Click any link to view details

There are several ways to create knowledge links:

Method 1: From an Incident (Most Common)

When resolving a support ticket or incident:

  1. Open the incident (e.g., a support ticket)
  2. Find the knowledge field on the page (e.g., "Knowledge Links" or "Related Articles")
  3. Click "Link knowledge" or "Add knowledge link"
  4. Fill in the form:
  5. Incident: Pre-filled with current incident
  6. Article/Content: Search for and select the article that resolved the issue
    • Start typing to search
    • Select from the dropdown
    • If article doesn't exist, you may need to create it first
  7. Additional fields: Depending on your configuration, fill in any custom fields
  8. Click "Save"

What happens: - Knowledge link is created - Link appears on both the incident and the article - Statistics are updated - Your competency may be updated (if tracking is enabled)

Method 2: From an Article

When you want to add a support case to an existing article:

  1. Open the article
  2. Find the knowledge field
  3. Click "Link knowledge"
  4. Fill in the form:
  5. Article: Pre-filled with current article
  6. Incident: Search for and select the incident
  7. Click "Save"

Method 3: Direct Creation

Create a knowledge link independently:

  1. Navigate to Content > Knowledge
  2. Click "Add knowledge"
  3. Select the knowledge type
  4. Fill in the form:
  5. Incident: Select the incident entity
  6. Article: Select the target article
  7. Knowledge type: Pre-selected based on your choice
  8. Click "Save"

If you have permission to edit knowledge links:

  1. Find the knowledge link (on article, incident, or knowledge list)
  2. Click "Edit" next to the link
  3. Modify fields as needed
  4. Click "Save"

Note: You can usually edit your own knowledge links. Editing others' links requires special permission.

To remove an incorrect or duplicate link:

  1. Find the knowledge link
  2. Click "Delete" or "Remove"
  3. Confirm deletion

Warning: This cannot be undone. The link is permanently removed, though the original incident and article remain.

Understanding Citations

The system automatically distinguishes between:

  • Direct Knowledge: You're linking to content you created
  • Your name appears as both knowledge creator and content author

  • Counts toward your "original content" metrics

  • Citation: You're linking to someone else's content

  • Different authors for knowledge link and content
  • Counts as "reused content"
  • Helps track content reuse and popularity

This happens automatically based on authorship.

Each knowledge link tracks:

  • Created: When the link was made
  • Changed: Last modification time
  • Author: Who created the link
  • Incident Owner: Who owns the incident
  • Frequency: How recently this link was created
  • Short: Within configured short period (default 15 days)
  • Medium: Within medium period (default 90 days)
  • Long: Within long period (default 365 days)

Articles display aggregate statistics: - Total links: How many incidents link to this article - Recent links: Links in short period - Citations: How many people link to this content

Managing Your Competency

If competency tracking is enabled, monitor and improve your knowledge management skills.

Viewing Your Competency

Access your competency status:

  1. Go to your user profile (click your name, then "View profile")
  2. Find the Competency section
  3. Or navigate directly to your competency record (link provided on profile)

What you'll see: - Current role: Candidate, Contributor, or Publisher - Progress: Percentage of competencies completed - Correct/Total: X out of Y competencies achieved - Completed: Date you achieved 100% (if applicable) - Coach: Your assigned mentor - Leader: Person who approves your advancement

Understanding Competency Roles

Candidate

Entry-level knowledge management role

Responsibilities: - Learn knowledge linking basics - Create simple knowledge links - Follow established procedures - Ask questions when unsure

Competencies typically include: - Understanding knowledge types - Creating accurate links - Using search effectively - Following standards

Contributor

Experienced knowledge management role

Responsibilities: - Create complex knowledge links - Mentor candidates - Maintain high accuracy - Identify improvement opportunities

Competencies typically include: - Recognizing citation vs. direct knowledge - Creating quality documentation - Maintaining adherence standards - Effective content reuse

Publisher

Advanced knowledge management role

Responsibilities: - Review and approve content - Set quality standards - Analyze reports - Lead improvement initiatives

Competencies typically include: - Content quality assessment - Team performance analysis - Process improvement - Strategic planning

Progressing Through Roles

Step 1: Complete Competencies

  • Focus on current role's competencies
  • Practice regularly
  • Ask your coach for guidance
  • Track your progress

Step 2: Request Proposal

When you believe you're ready:

  1. Contact your coach
  2. Discuss your progress
  3. Request competency review
  4. Coach evaluates your work

Step 3: Coach Proposes

If coach agrees you're ready:

  1. Coach accesses your competency record
  2. Coach clicks "Propose for [Next Role]"
  3. Proposal is recorded with timestamp
  4. Your leader is notified (if configured)

Step 4: Leader Approves

Your leader reviews the proposal:

  1. Leader accesses your competency record
  2. Leader reviews your achievements
  3. Leader clicks "Approve for [Next Role]"
  4. Your role is updated
  5. You receive new permissions
  6. You're notified (if configured)

If not approved: - Leader provides feedback - You work on identified gaps - You reapply when ready

Tips for Competency Growth

  1. Regular practice: Create knowledge links consistently
  2. Quality over quantity: Focus on accuracy
  3. Learn from others: Review high-quality knowledge links
  4. Ask questions: Work with your coach
  5. Review reports: Understand your metrics
  6. Accept feedback: Use it to improve
  7. Help others: Mentoring reinforces learning

Creating Adherence Records

Adherence tracking ensures knowledge linking standards are met.

When to Create Adherence Records

Typically created: - During incident reviews - Quality audits - Performance evaluations - Compliance checks

Check with your supervisor about when you should create adherence records.

Creating an Adherence Record

  1. Navigate to Content > Knowledge > Adherence (/admin/content/knowledge/adherence)
  2. Click "Add Adherence"
  3. Fill in the form:

Required Information

  • Name: Brief description (e.g., "Ticket #12345 Review")
  • Incident: Select the incident being reviewed
  • Learner: Select the person being evaluated (who handled the incident)
  • Disposition: How the incident was resolved

Evaluation Criteria

Answer these questions about the incident:

  • Article Required: Was linking knowledge required?
  • Yes: Incident needed documentation
  • No: Simple inquiry, no docs needed

  • N/A: Unclear or exception case

  • Article Linked: Was knowledge actually linked?

  • Yes: Knowledge was linked
  • No: Knowledge was not linked

  • N/A: Not applicable

  • Reused: Was article created or reused?

  • Created: New article written
  • Reused: Existing article used

  • N/A: No article involved

  • Accurate: Was the linked article accurate?

  • Yes: Article correctly addressed the issue
  • No: Article was incorrect or incomplete

  • N/A: No article to evaluate

  • Improve: Should the article be improved?

  • Yes: Article needs updates
  • No: Article is fine as-is

  • N/A: No article to evaluate

  • Found: Could you find an appropriate article?

  • Yes: Appropriate article exists
  • No: Gap in documentation

  • N/A: Didn't search

  • Add any notes in the notes field

  • Click "Save"

Interpreting Adherence Results

Perfect Adherence

Required: Yes
Linked: Yes
Reused: (either)
Accurate: Yes
Improve: No
Found: Yes

Documentation Gap

Required: Yes
Linked: No
Found: No
Action: Create missing documentation

Accuracy Issue

Required: Yes
Linked: Yes
Accurate: No
Improve: Yes
Action: Update incorrect article

Training Opportunity

Required: Yes
Linked: No
Found: Yes
Action: Train user on search/linking

Performing Quality Reviews

Quality reviews assess knowledge article quality using structured criteria.

When to Perform Quality Reviews

Quality reviews are typically done: - Before publishing new articles - During periodic content audits - When articles are flagged for improvement - As part of content moderation workflow

Creating a Quality Review

  1. Navigate to the article to be reviewed
  2. Click "Add Quality Review" (if available) or go to Content > Knowledge > Quality
  3. Click "Add Quality"
  4. Fill in the form:

Basic Information

  • Entity: Select the article being reviewed
  • Revision: Select specific revision (usually latest)
  • Reviewer: Auto-filled with your user

Quality Criteria

For each criterion, check the box if met:

Content Quality: - ☐ Information is factually correct - ☐ Matches current product version - ☐ No contradictions present - ☐ All necessary steps included - ☐ Prerequisites clearly listed - ☐ Expected outcomes described

Clarity: - ☐ Language is clear and concise - ☐ Terms are defined - ☐ Instructions are unambiguous

Format: - ☐ Uses appropriate headings - ☐ Steps are numbered - ☐ Formatting is consistent - ☐ Screenshots are current - ☐ Images are clear and relevant

Compliance: - ☐ Follows style guide - ☐ Uses approved terminology - ☐ Meets accessibility standards

Your organization may have different criteria

  1. Add reviewer notes (optional but recommended)
  2. Click "Save"

Understanding Quality Scores

The system automatically calculates a quality score:

Score = 100 × (Checked items - Unchecked items) / Total items

Example: - 8 criteria checked - 2 criteria unchecked - 10 total criteria - Score = 100 × (8 - 2) / 10 = 60

Score ranges: - 90-100: Excellent - approve for publication - 75-89: Good - minor improvements needed - 60-74: Fair - significant revision needed - 50-59: Poor - major revision required - <50: Failing - complete rewrite recommended

Following Up on Quality Reviews

After creating a review:

  1. Author is notified (if configured)
  2. Based on score:
  3. High score: May auto-publish
  4. Medium score: Author revises
  5. Low score: Supervisor involved
  6. Author makes improvements
  7. Re-review if necessary
  8. Approve for publication when quality meets standards

Quality Review Best Practices

  1. Be objective: Follow criteria exactly
  2. Be thorough: Check every criterion
  3. Add notes: Explain unchecked items
  4. Be constructive: Suggest improvements
  5. Be consistent: Apply standards equally
  6. Test steps: Try procedures yourself
  7. Consider audience: Does it serve their needs?

Using Reports

Access knowledge management reports to track performance and identify improvements.

Accessing Reports

Navigate to Reports > Knowledge (/admin/reports/knowledge)

Available Reports

Competency Report

Location: Reports > Knowledge > Competency

What it shows: - User competency progression - Role distribution - Completion rates - Pending proposals/approvals - Coach/leader assignments

Use it to: - Track team development - Identify coaching opportunities - Monitor approval pipeline - Plan training needs

Knowledge Activity Report

What it shows: - Knowledge links created over time - Knowledge by type - Most active users - Citation vs. direct knowledge - Frequency distributions

Use it to: - Understand usage patterns - Identify power users - Track content reuse - Monitor system adoption

Adherence Report

What it shows: - Adherence rates by user/team - Common dispositions - Article accuracy rates - Documentation gaps - Improvement needs

Use it to: - Identify training needs - Find documentation gaps - Measure process compliance - Recognize high performers

Quality Report

What it shows: - Average quality scores - Quality trends over time - Articles needing improvement - Reviewer activity - Quality by content type

Use it to: - Maintain content standards - Prioritize content updates - Evaluate reviewer performance - Track quality improvements

Creating Custom Reports

Use Views to create custom reports:

  1. Navigate to Structure > Views > Add view
  2. Select data source:
  3. Knowledge entities
  4. Knowledge Competency
  5. Knowledge Adherence
  6. Knowledge Quality
  7. Add fields you want to display
  8. Add filters to limit data
  9. Add sorting for organization
  10. Choose display format:
  11. Table
  12. Grid
  13. List
  14. Chart (if Charts module enabled)
  15. Save your view

Best Practices

  1. Link immediately: Create links while information is fresh
  2. Search first: Check if article already exists before creating new
  3. Be accurate: Link only relevant, correct articles
  4. Add context: Use custom fields to provide details
  5. Update if needed: Fix errors promptly
  6. Cite sources: Use citations appropriately
  7. Follow standards: Adhere to organizational guidelines

For Article Quality

  1. Clear titles: Use descriptive, searchable titles
  2. Step-by-step: Break complex procedures into steps
  3. Current information: Keep content up-to-date
  4. Screenshots: Include current, clear images
  5. Test procedures: Verify steps work
  6. Consistent format: Follow style guide
  7. Proper tagging: Use appropriate categories/tags

For Competency Growth

  1. Set goals: Work toward next role
  2. Track progress: Review competency regularly
  3. Seek feedback: Ask coach for guidance
  4. Learn continuously: Study high-quality examples
  5. Practice: Consistent activity builds skill
  6. Help others: Teaching reinforces learning
  7. Document lessons: Share what you learn

For Adherence

  1. Be honest: Report accurately
  2. Be timely: Record soon after incident
  3. Be complete: Fill all fields
  4. Be constructive: Focus on improvement
  5. Follow up: Act on identified gaps
  6. Share insights: Help improve processes

For Quality Reviews

  1. Be systematic: Check every criterion
  2. Be fair: Apply standards consistently
  3. Be specific: Explain findings clearly
  4. Be helpful: Suggest improvements
  5. Be timely: Review promptly
  6. Be thorough: Test procedures
  7. Be collaborative: Work with authors

Troubleshooting

Common Issues and Solutions

Possible causes: - Missing permissions - Knowledge field not enabled on content type - No knowledge types configured

Solutions: 1. Check permissions with administrator 2. Verify knowledge field exists on content type 3. Ask administrator to create knowledge types

"I can't find the article I need"

Solutions: 1. Try different search terms 2. Check article title and tags 3. Browse by category 4. Ask colleagues 5. Consider creating new article if gap exists

"My competency isn't updating"

Possible causes: - Competency calculation delayed - Criteria not properly configured - Permissions issue

Solutions: 1. Clear cache (ask administrator) 2. Wait for cron run (if using scheduled updates) 3. Contact your coach or administrator

"Quality score seems wrong"

Causes: - Formula includes negative scoring - Not all criteria were checked - Custom criteria configured differently

Solutions: 1. Review checked vs. unchecked items 2. Understand scoring formula 3. Ask administrator about criteria configuration

Causes: - Permission restrictions - Content moderation status - Audience restrictions

Solutions: 1. Check your user role permissions 2. Verify content is published 3. Contact content owner or administrator

Getting Additional Help

If you encounter issues:

  1. Check documentation: Review relevant guide sections
  2. Ask your coach: Competency-related questions
  3. Contact supervisor: Process questions
  4. Contact administrator: Technical issues
  5. Check error messages: Provide details when asking for help

Next Steps

Now that you understand the basics:

  1. Practice: Create test knowledge links
  2. Explore: Review existing knowledge links
  3. Learn: Study high-quality examples
  4. Engage: Work with your coach
  5. Improve: Act on feedback
  6. Share: Help train others

For detailed configuration information, see the Configuration Guide.

For technical details and customization, see the API Documentation.