The playbook for building a knowledge base that powers AI answers

TL;DR

• If you've ever written a help article that nobody found – or that customers ignored and opened a ticket anyway – this guide is for you. A knowledge base is the one place all your support content lives, powering your customer portal, your CX agent, and Computer's AI-powered answers, all from the same content.
• This guide teaches you how to set up, structure, and optimize your knowledge base in DevRev – step by step, with best practices baked in.
• Get it right, and you're looking at 60-80% deflection rates. Get it wrong, and your customers are still opening tickets for questions you've already answered somewhere.

Before you write a single article, do this

Let's start at the beginning. Your knowledge base lives in Settings › Support › Knowledge Base. This is your central hub – where you create articles, manage collections, configure visibility, and track performance.

Before you start creating content, make sure your permissions are in order:

• All team members with edit rights can create and modify articles.
• Publisher group members can publish articles (with or without approval workflows).
• Admins can delete articles and perform all management functions.

Need to give someone publisher rights? Head to Settings › User Management › Internal Groups › Publisher Group › + User.

The anatomy of a knowledge base (three concepts, zero confusion)

Your knowledge base is built on three core concepts. Understanding how they relate to each other saves you a lot of restructuring later.

Articles – your building blocks

An article is a single document containing information about your products, services, or processes. Every article needs:

Collections – your organizing structure

Collections are the themed categories that group articles on your customer portal. Think of them as chapters in a help center that your customers browse.

• Collections and parts are distinct entities – collections organize the portal; parts represent your product structure.
• You can nest collections within other collections to create multi-level hierarchies.
• The order of collections on your help center matches their arrangement in your DevRev account.

Parts – your product map

Parts represent your product hierarchy (products, capabilities, features). Every article must link to at least one part, which helps Computer understand what product area the content belongs to.

Your first article in under five minutes

Here's the step-by-step:

1. Go to Settings › Support › Knowledge Base.
2. Click +Article at the top of the page.
3. Provide a title and description.
4. Choose your content method:
   • Write a new article using the built-in rich-text editor.
   • Link to an existing article hosted on an external website.
   • Upload a file (PDF or MS Word document).
5. Configure settings: Part, Owned by, Status, Collection, and Visible to.
6. Click Create and select one of:
   • Create (saves as draft).
   • Create and submit for review (sends to reviewers).
   • Publish (makes it immediately visible to customers).

The rich-text editor – your formatting toolkit

Type / (slash command) in the editor to access:

• Text formatting. Headers (H1, H2, H3), bold, italic, underline.
• Structure. Bullet lists, numbered lists, tables, callouts, quotes.
• Media. Images, video embeds (YouTube, Loom, Vimeo, Wistia).
• Special elements. Hyperlinks, code blocks, content blocks.
• AI assistance. Select text and use Ask AI to rephrase, lengthen, shorten, or correct content.

Pro tip: Use header tags (H1, H2, H3) consistently – they automatically generate a table of contents on the customer portal and improve Computer's search performance.

Content blocks – write once, reuse everywhere

Content blocks are reusable snippets (text, images, tables, videos) that you insert across multiple articles. Update the block once, and every article using it updates automatically.

• Create: Settings › Support › Content Blocks › Create Content Block.
• Insert: In the article editor, type / and select Content Block.
• Unlink: To edit a content block independently for one specific article, hover over it, click the 3-dot menu, and select Unlink.

Published doesn't mean finished

Managing your articles day-to-day

Editing: Open the article › click the full screen icon › click the pen icon (top right) › make changes › Save or Publish.

• Save creates a new draft version without affecting what customers currently see.
• Publish creates a new version and makes changes visible immediately.

Version control: Every edit saves a new version. To restore a previous version, open the article › 3-dot menu › Versions › Restore version.

Bulk operations: Select multiple articles in the main KB view to change statuses or delete in bulk (admin privileges required for deletion).

The approval workflow – quality before speed

For teams that need review cycles (especially in regulated industries), the approval workflow gives you control:

The flow: Create article → Submit for review → Reviewers approve (or request changes) → Publisher publishes.

By default, all team members have drafter and approver rights but not publisher rights. This keeps content quality high without slowing people down.

The visibility puzzle: who sees what (and why it trips everyone up)

Visibility is where teams trip up most often. Here's how it works:

The critical rule: Article visibility depends on both the article and collection settings. A public article inside a non-public collection won't be visible to anyone. Make sure your collection is published if you want its articles to appear.

Enabling public access: Settings › Plug & Portal › Portal Settings › enable Help Center and Public Portal.

Collections done right: think like your customer, not your org chart

Creating a collection is straightforward: Settings › Support › Article Collections › +Collection › fill in title, description, parent › enable Publish Collection › Create.

But the strategy behind your collection structure matters more than the mechanics.

Four rules for collections that work

1. Organize by customer intent, not your org chart. "How do I get started?" beats "CS team processes." Your customers don't know or care about your internal structure.
2. Keep nesting shallow. One to two levels of sub-collections is ideal. Deep nesting makes content hard to find.
3. Align collection and article visibility. A public article in a private collection is invisible. Check both.
4. Use descriptive names. The collection name should tell customers what they'll find inside – immediately.

Writing for humans and AI at the same time (nine rules that make both happy)

This is where knowledge base management gets genuinely interesting. Computer breaks your articles into smaller chunks (paragraphs and sentences) to power search. Every paragraph is a module that might get surfaced independently as an answer.

Nine rules for AI-optimized content

1. One topic per article. Tight cohesion – each article covers a single subject.
2. Use header tags (H1, H2, H3). They improve search performance and auto-generate the table of contents.
3. Write meaningful descriptions. They enhance search relevance and serve as SEO signals.
4. Use intent-driven titles. "How to close X account" – not "Account closure procedures."
5. Paragraph discipline. Each paragraph should make sense when read in isolation. Avoid starting with "In addition" or "Next."
6. Minimize tables. Two-column tables can usually be written as lists for better AI readability.
7. Include text alternatives for media. Images and videos aren't currently used to train the model – always include supporting text.
8. Use approved terminology consistently. No jargon, no code names.
9. Be specific with pronouns. "Computer" not "it." "The article" not "this." Clear antecedents every time.

When to split vs. combine

The scoreboard: metrics that tell you what's working (and what's not)

Go to Settings › Support › Article Analytics for your performance dashboard.

What to track

What to act on

• High-view, low-upvote articles. Being found but not helpful – rewrite the content.
• Top-viewed articles. Your most critical content – keep it accurate and current.
• Zero-view articles. Either niche topics or discoverability problems (poor titles, wrong collections, visibility misconfiguration).
• Channel distribution. Understand whether customers find articles through PLuG, the portal, or AI-powered search.

The magic layer: how Computer turns your articles into instant answers

Computer operates in two modes for customer-facing conversations:

1. Suggest-only mode. Computer suggests an answer to your support agent, who can accept, edit, or reject it before sending.
2. Content-powered mode. Computer automatically replies to customer queries before they reach a human. It searches the knowledge base, generates an answer, and confirms with the customer whether it was useful.

Computer prioritizes QnA pairs as definitive answers to frequently asked questions, then falls back to article content for broader queries.

Knowledge gap detection

Computer can also identify where your documentation is falling short:

• Detects when a human agent had to intervene because documentation was missing.
• Captures the query and the agent's manual response.
• Auto-generates a Q&A article in draft state for your review.
• Cross-checks existing docs before creating new content to avoid duplication.

All auto-generated articles stay in draft until human review – ensuring accuracy, brand tone, and compliance.

Now go build something your customers will thank you for

We designed the knowledge base in Computer to be the kind of tool you set up in an afternoon and refine over time – not a six-month documentation project. Start with your top five customer questions, get them published, and let the data guide what you write next.

Every article you publish means one less ticket tomorrow, one faster answer today – and an AI that genuinely gets your product. Start with five questions. The data will show you where to go next.