AI Skill Report Card
Writing Knowledge Base Articles
Quick Start14 / 15
Given: issue details, article type, system/application, and audience, produce a structured KB article.
Input:
- Issue: VPN client fails to connect after Windows update, error "Tunnel not found"
- Type: Troubleshooting
- System: Cisco AnyConnect VPN
- Audience: End User (Non-Technical)
Output: Full KB article with Title, Symptoms, Affected Versions/Environments,
Prerequisites, Resolution Steps, Still Having Issues? section — written in
plain language with menu paths spelled out, no jargon.
No preamble — go straight to the structured article.
Recommendation▾
Add an example for FAQ or Known Issue type to cover more of the five article-type skeletons in action, not just Troubleshooting.
Workflow14 / 15
Progress:
- Step 1: Identify article type (Troubleshooting / How-To / FAQ / Known Issue / Getting Started) — this sets the skeleton
- Step 2: Identify audience — this sets vocabulary, assumed knowledge, and depth
- Step 3: Write the title as a searchable phrase matching what a user would type, not the internal fault name
- Step 4: Write Symptoms as "Users experiencing this issue may see/report…" — concrete, observable, on-screen language
- Step 5: Write Affected Versions/Environments — pin to what was actually tested; flag unknowns explicitly
- Step 6: Write Prerequisites (access level, tools, permissions needed before starting)
- Step 7: Write Resolution as numbered steps, register-matched to audience (see Audience Calibration)
- Step 8: For Known Issue type, replace Resolution with Workaround (if any) + explicit "no confirmed fix yet" statement
- Step 9: Add closing section (escalation path / related articles / "still stuck?")
- Step 10: Flag anything that needs human verification (version-specific paths, internal system names)
Recommendation▾
Include a brief note on handling ambiguous/missing input (e.g., what to do if audience or article type isn't specified).
Article Type Skeletons
- Troubleshooting: Symptoms → Affected Versions/Environments → Prerequisites → Resolution Steps → Escalation
- How-To Guide: Goal statement → Prerequisites → Numbered Steps → Verification ("you'll know it worked when…") → Related Tasks
- FAQ: Grouped Q&A, each answer self-contained (no "see above")
- Known Issue: Symptoms → Affected Environments → Root Cause (if known, else "under investigation") → Workaround → Status
- Getting Started: Overview → Prerequisites → First-Run Steps → Common Next Steps → Where to Get Help
Audience Calibration
| Audience | Vocabulary | Steps include | Assumes |
|---|---|---|---|
| End User (Non-Technical) | Plain language, no jargon | Exact menu paths, screenshots-style descriptions, click-by-click | Nothing — explain where every button is |
| IT Staff / Helpdesk | Standard IT terms | Diagnostic steps, ticket-escalation triggers | Familiarity with ticketing tools and basic OS navigation |
| Developer / Technical | Technical terms, API/config names | Config snippets, log locations, error codes | Comfortable in code/config, no hand-holding on syntax |
| System Administrator | Full technical register | Shell commands, service restarts, permission levels | Shell/console access, elevated privileges |
Examples18 / 20
Example 1: Input: Issue: "Outlook keeps prompting for password on Mac after SSO rollout." Type: Troubleshooting. System: Microsoft 365. Audience: End User. Output:
# Outlook on Mac Keeps Asking for Your Password
Recommendation▾
Consider a short template block per article type (bare skeleton with placeholders) in addition to the prose skeleton descriptions for faster scanning.
Symptoms
You may notice:
- Outlook repeatedly asks you to sign in, even after entering the correct password
- A sign-in window pops up every few minutes
- Email stops syncing until you dismiss the prompt
Affected Versions
- Outlook for Mac (all versions), after company SSO rollout (verify against your rollout date)
Prerequisites
- Your company email address
- Access to your Mac's login password
Resolution Steps
- Quit Outlook completely (Outlook menu > Quit Outlook)
- Open Keychain Access (search for it in Spotlight)
- Search for "outlook" and delete any entries related to your email address
- Reopen Outlook and sign in when prompted, using the Company Portal SSO screen (not the plain password box)
- Check "Remember my credentials" before finishing
Still Having Issues?
Contact the helpdesk and mention you tried the Keychain reset above.
**Example 2:**
Input: Same issue, Audience: System Administrator.
Output:
Recurring Auth Prompts in Outlook for Mac Post-SSO Migration
Symptoms
- Users report repeated OAuth prompts in Outlook for Mac
- Correlates with stale Kerberos/SSO tokens post ADFS cutover
Affected Environments
- Outlook for Mac, tenants migrated to SSO after [date] — confirm against your migration log
Prerequisites
- Admin access to Azure AD / ADFS console
- Ability to push Keychain reset via Jamf or equivalent MDM
Resolution Steps
- Confirm affected users' token cache via
azureadincidentreportor equivalent - Push a Keychain cleanup profile via MDM targeting
com.microsoft.outlookentries - Force re-auth by revoking the refresh token in Azure AD for affected accounts
- Validate SSO conditional access policies aren't double-prompting due to legacy + modern auth overlap
- Monitor sign-in logs for repeat failures over 24h
Escalation
If prompts persist after token revocation, escalate to Identity team — likely conditional access policy conflict.
Best Practices
- Write Symptoms in the user's words, not the engineer's — search terms, not root causes.
- Never write the same steps for two audiences — regenerate per audience even from identical notes.
- Pin "Affected Versions" to what was actually tested; write "verify against your version" rather than guessing.
- For Known Issue articles, never imply a fix exists if it doesn't — state workaround and status honestly.
- Strip internal hostnames, ticket system names, and credentials from anything destined for a public-facing help center.
- Keep FAQ answers self-contained — a user may land on one Q&A via search with no other context.
Common Pitfalls
- Don't write a sysadmin-register article and hand it to end users (or vice versa) — mismatched register creates tickets instead of deflecting them.
- Don't skip the Symptoms section or make it vague ("issue with login") — specificity is what makes the article findable.
- Don't state resolution steps as fact when versions weren't verified — flag assumptions instead.
- Don't blur Known Issue with Troubleshooting — a Known Issue article must not claim a resolution it doesn't have.
- Don't leave internal-only references (VPN names, internal tools) in a public-facing End User article.