Skip to content

User Guide

This guide explains how to use the Knowledge module's features for day-to-day Knowledge-Centered Success work.

Table of Contents

Getting Started

Understanding Knowledge-Centered Success

The Knowledge module helps organizations connect support incidents (like tickets, issues, or cases) with knowledge articles (like help documents, FAQs, or solutions). Follow the Solve Loop: Reuse, Improve, Capture, Structure.

Key benefits: - Find relevant documentation quickly - Track which articles are most useful - Identify documentation gaps - Measure Process Alignment - Track personal growth in proficiency

Your Role

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 proficiency 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 proficiency 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 Proficiency

If proficiency tracking is enabled, monitor and improve your proficiency.

Viewing Your Proficiency

Access your proficiency status:

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

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

Understanding Proficiency Roles

Candidate

Entry-level proficiency role

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

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

Contributor

Experienced proficiency role

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

Proficiency items typically include: - Recognizing citation vs. direct knowledge - Creating quality documentation - Maintaining Process Alignment standards - Effective content reuse

Publisher

Advanced proficiency role

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

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

Progressing Through Roles

Step 1: Complete Proficiency Items

  • Focus on current role's proficiency items
  • 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 proficiency review
  4. Coach evaluates your work

Step 3: Coach Proposes

If coach agrees you're ready:

  1. Coach accesses your proficiency 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 proficiency 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 Proficiency 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 Process Alignment Records

Process Alignment Review samples whether knowledge linking practices were followed.

When to Create Process Alignment Records

Typically created: - During incident reviews - Content Standard Checklist coaching - Performance evaluations - Compliance checks

Check with your supervisor about when you should create Process Alignment records.

Creating a Process Alignment Record

  1. Navigate to Content > Knowledge > Process Alignment (/admin/content/knowledge/alignment)
  2. Click "Add Process Alignment"
  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 Process Alignment Results

Perfect Process Alignment

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

Recording Content Standard Checklist Samples

A Content Standard Checklist sample is six coaching checks on an article. It is not a test score.

When to Record a Sample

The coach samples closed or reused articles. A sample is not required on every save. Technical accuracy is reuse-is-review.

Creating a Content Standard Checklist Sample

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

Basic Information

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

The Six Checks

For each check, mark it if met:

  • ☐ Complete — Issue, Environment, Cause, and Resolution are present
  • ☐ Content Clear — A reader can follow the article without guessing
  • ☐ Unique — The article does not duplicate another article
  • ☐ Title Relates to Article — The title matches what the article is about
  • ☐ Metadata Correct — Metadata matches the article

  • ☐ Hyperlinks Valid — Links resolve and point at the right targets

  • Click "Save"

Understanding Content Standard Checklist Samples

The form is a coaching sample, not a test score. Technical accuracy is reuse-is-review. The listing shows checks met (for example 4 of 6). Do not treat getScore() as a pass/fail grade. Trends belong in the analytic namespace.

Following Up on Samples

After recording a sample:

  1. Author is notified (if configured)
  2. Author makes improvements for checks that were not met
  3. Re-sample if necessary

Content Standard Checklist Best Practices

  1. Be objective: Follow the six checks
  2. Be thorough: Check every item
  3. Add notes: Explain unchecked items
  4. Be constructive: Suggest improvements
  5. Be consistent: Apply the Content Standard equally

Using Reports

Access knowledge reports to track performance and identify improvements.

Accessing Reports

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

Available Reports

Proficiency Report

Location: Reports > Knowledge > Proficiency

What it shows: - User proficiency 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

Process Alignment Report

What it shows: - Process Alignment 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

Content Standard Checklist Report

What it shows: - Checks met - Articles needing improvement - Reviewer activity - Samples by content type

Use it to: - Maintain the Content Standard - Prioritize content updates - Track coaching samples

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 Proficiency
  5. Knowledge Process Alignment
  6. Knowledge Content Standard Checklist
  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 the Content Standard

  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 Proficiency Growth

  1. Set goals: Work toward next role
  2. Track progress: Review proficiency 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 Process Alignment

  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 Content Standard Checklist Samples

  1. Be systematic: Check every item
  2. Be fair: Apply the Content Standard consistently
  3. Be specific: Explain findings clearly
  4. Be helpful: Suggest improvements
  5. Be timely: Sample promptly
  6. Be thorough: Read the article
  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 proficiency isn't updating"

Possible causes: - Proficiency 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

"Checks met seems wrong"

Causes: - Not all six checks were marked - A check was misunderstood

Solutions: 1. Review marked vs. unmarked checks 2. Ask your coach about the Content Standard

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: Proficiency-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.