Knowledge Toolkit
Knowledge Article Style Guide
Consistency is key to effective knowledge management. This style guide defines fonts, headings, and text structure used across knowledge articles.
- Use the pre-built Knowledge Article Template to automatically apply these formatting standards.
- If creating manually, follow the table below to ensure consistency.
| Backend Style | Use Case | Default Font | Default Font Size | Public View Font | Public View Size |
|---|---|---|---|---|---|
| Paragraph | Body text throughout KB | Verdana | 10pt | Public Sans | 10pt |
| Heading 2 | Main section headings | Verdana | 14pt | Ringside Narrow SSm | 30pt |
| Heading 3 | Subheadings | Verdana | 12pt | Ringside Narrow SSm | 24pt |
| Preformatted | Code snippets or script lines | Monospace | 8pt | Monospace | 8pt |
Tip: Clean, consistent formatting improves readability and user trust.
Writing a Knowledge Article
Well-written knowledge articles make it easier for users to solve problems on their own and reduce repeat incidents. Articles should be concise, clear, and actionable — written with the reader in mind.
| Best Practice | Why It Matters | Example |
|---|---|---|
| Start With a Clear Purpose | Sets reader expectations immediately. | “How to reset your Duo 2FA token” vs. “Duo Notes.” |
| Use Concise, Action-Oriented Language | Reduces confusion and speeds up resolution. | “Click Settings > Security > Reset Token.” |
| Follow a Logical Structure | Improves readability and scannability. | Purpose → Symptoms → Resolution → Notes. |
| Write for the Audience | Makes the KB useful for anyone, not just technical staff. | Replace jargon with plain language and context. |
| Include Visuals When Helpful | Enhances understanding for complex steps. | Add screenshots or terminal examples. |
| Add Keywords & Alternate Terms | Improves search results and discoverability. | Include “VPN,” “remote access,” “network error.” |
| Keep It Current | Prevents outdated guidance and new incidents. | Update KBs when tools or processes change. |
| Close With Limitations or Next Steps | Guides users on what to do if the issue isn’t resolved. | “If unresolved, submit a ticket with subject ‘VPN Escalation.’” |
The Importance of Feedback
Feedback is the most important part of keeping knowledge useful. Every knowledge article includes a built-in feedback section — this is your direct line to flag errors, request clarification, or suggest improvements. Articles are living documents, and every time someone reads or uses one, there’s an opportunity to make it better.
The faster and more specific the feedback, the more reliable and valuable our knowledge base becomes.
| Best Practice | Why It Matters | Example |
|---|---|---|
| Be Specific | Helps the author know what to fix. | “Step 3 doesn’t match the current UI — the button is now labeled ‘Connect.’” |
| Add Context | Explains what you were doing and where the issue occurred. | “On macOS, I couldn’t find the settings screen shown in Step 2.” |
| Suggest a Fix | Speeds up the editing process. | “Add a note that users may need to restart before Step 5 works.” |
| Use Feedback Early and Often | Articles evolve over time — don’t wait to report issues. | Submit feedback immediately when you spot an error. |
| Respond Promptly (Authors) | Builds trust and keeps knowledge current. | Review feedback weekly and resolve it quickly. |
Remember:
- If you see something, say something.
- If you receive feedback, address it quickly.
- If you use an article often, make sure it’s always accurate.
KCS (Knowledge-Centered Service)
Knowledge-Centered Service (KCS) is an industry-standard approach to building and maintaining knowledge directly within the support process. Rather than treating knowledge as something written after the work is done, KCS integrates it into the day-to-day workflow — capturing, improving, and evolving knowledge in real time.
While we’re not implementing the full KCS methodology today, we are adopting one of its most impactful principles: continuous improvement through usage and feedback. Think of it like a “see something, say something” approach — if you find a gap, inconsistency, or error in an article, speak up so we can fix it.
| Principle | What It Means | Example in Practice |
|---|---|---|
| Capture as You Work | Document solutions during the process — not afterward. | While resolving a ticket, you write the steps you took directly into a draft KB before closing it. |
| Use It to Improve It | Treat every article as a living document that can always get better. | After using a KB, you notice an outdated screenshot and update it immediately. |
| Evolve Knowledge with Demand | Articles should grow and change as needs evolve. | You add new troubleshooting steps as product features are updated. |
| Collaborate and Contribute | Everyone should help improve knowledge, not just the original author. | A Tier 2 engineer adds advanced troubleshooting tips to a Service Desk article. |
| Feedback is Fuel | Feedback keeps knowledge accurate, useful, and relevant. | A user flags that a step is outdated. The article is updated within a day. |