Aug 20, 2025
TL;DR: Put your help content inside the client portal, structure it for jobs-to-be-done, tune search for first-try success, and lock down permissions with least-privilege. You’ll cut repetitive tickets, reduce “any update?” emails, and give customers a confident self-service path. If you want this working out of the box (with AI search that cites your content), start with dokky.io.
Why embed the knowledge base in your portal?
A standalone help site forces context switching. A portal-embedded KB meets customers where collaboration already happens—next to pages, files, tasks and approvals—so they can:
Find answers at the point of need
See client-specific examples and files
Turn answers into actions (tasks) without leaving the page
Leave an auditable trail of views and decisions
Result: fewer tickets, faster resolutions, happier clients.
The three levers: IA, Search, Permissions
Think of deflection as a system. When all three levers are tuned, your ticket volume drops without harming experience.
1) Information Architecture (IA): organise for action
Design your KB around the things customers actually need to do, not your org chart.
Recommended top level
Start here – orientation, how to get help, what “good” looks like in week one
How-to guides – short, task-centred instructions; every guide ends with a checklist or next step
Troubleshooting – symptoms → likely causes → fixes → when to escalate
Policies & billing – SLAs, security, invoicing, renewals
Release notes – scannable updates with links to impacted guides
Integrations – one page per integration: prerequisites, setup, validation, rollback
Naming rules
Use customer language, not internal jargon
Front-load the verb: “Connect SSO (Okta)” > “SSO connection”
One job per article; if you need a table of contents, split it
10 high-impact articles to publish first
Invite users & set permissions
Connect SSO
Upload brand assets
Submit a great support request (what to include)
Grant environment access safely
Approve a change (with audit trail)
Integration: CRM
Integration: Analytics
Billing and renewals explained
Where to find updates, deadlines and files in the portal
2) Search: optimise for first-query success
Most users won’t scroll. Make the first result the right result.
Search hygiene
Titles: start with the action (“Reset password”)
Synonyms: add tags for common variants (MFA, 2FA, two-factor)
Snippets: make the first 160 characters a plain-language answer
Disambiguation: add a one-line “Use this if…” at the top of look-alike articles
Signals to watch
Zero-result queries → what to write next
Bounce to ticket (article opened → immediate task/ticket) → improve that article
Query → article mapping → add anchors and quick answers to hit intent faster
Quick wins
Link “known-good” answers from task checklists and status updates
Add “Related articles” to every page
Use human file names (“Data Import Template.xlsx” > “v3_final_final.xlsx”)
3) Permissions: protect trust without friction
Share widely enough to reduce back-and-forth, but no wider.
Principles
Least privilege by default: start private, deliberately publish customer-safe content
Role-based access: admin, contributor, viewer—keep it simple
Per-client Spaces: examples, files and screenshots should match their setup
Auditability: track who viewed what, when, and what changed
What should be public vs private?
Public: generic concepts, stable how-tos, billing basics
Private (per client): environment specifics, keys, decisions, timelines
With dokky.io, permissions apply consistently across pages, files, tasks and the AI assistant—so the bot never shows what a user shouldn’t see.
Add AI (grounded) for instant, cited answers
An AI assistant in the portal can answer natural-language questions by retrieving from your KB and the client’s Space—and showing sources.
Ground on approved content only (no free-wheeling)
Respect permissions (Space-scoped retrieval)
Prefer tasks over paragraphs when work is required
Escalate gracefully when confidence is low or risk is high
You can see this approach in action with Dokky’s portal assistant: dokky.io.
Workflows that combine KB + portal (that actually deflect)
Onboarding in a day
Welcome page explains goals and timeline
“Start here” links to three essential guides and an approvals checklist
AI answers “Where do I upload assets?” and deep-links to the correct page
Support without the ping-pong
Customer searches “CSV import failed”
Top result shows error patterns and fixes; a “Still stuck?” button creates a task with logs and context
Assignee works from the task, not an email chain
Change approvals with evidence
Release notes link to the change guide
The guide includes an Approve task
Sharing history shows who viewed the guide and when they signed off
The inefficiency table (and how the portal fixes it)
InefficiencySymptomPortal + KB fixStatus ambiguity“What’s the latest?”Client-visible task board + activity feedLost context“Why did we change this?”Decision log co-located with artefactsDuplicate Q&ASame question weeklyKB article linked in updates; AI cites itVersion chaosMultiple “final” filesSingle file source linked across pages/tasksApproval driftWeeks waitingOne-click approvals with timestamps
Metrics that prove it’s working
Deflection rate: % of queries answered by KB/AI without escalation
First-answer helpfulness: 👍/👎 on the first response
Time to first value: days from invite to first self-service action
Coverage: % of top inbound queries with a strong article
Engagement depth: pages per session, return visits, file views
Even modest improvements here compound into real margin.
Common pitfalls (and fixes)
Wall-of-text articles → Split by job, add headings and checklists
Jargon and acronyms → Replace with customer language and synonyms
Out-of-date screenshots → Use neutral UI shots or captions clarifying differences
Private answers to public questions → Promote stable, non-sensitive guidance to public KB
Ungrounded AI → Tighten retrieval scope; improve the source article (don’t just tweak prompts)
FAQs
Is a portal KB just a copy of my public docs?
No. Keep public concepts public, but create private, client-specific versions where setup or examples differ.
How long should articles be?
Short enough to act on without scrolling. If there are multiple paths, use tabs or split into separate guides.
Do I need a technical writer?
Not at the start. Assign an owner per section and rotate monthly reviews.
What if customers still email?
Reply from the portal: link the relevant article or task and log the decision in the client’s Space. Habits shift quickly when the portal is the easiest path.