Blog Best practice

Knowledge base and self-service portal: a practical guide

How to design a knowledge base people actually use, organise the articles and run a self-service portal that cuts repeat requests.

Knowledge base and self-service portal: a practical guide
In this article
  1. What is a knowledge base?
  2. The two types of knowledge base
  3. What is a self-service portal?
  4. A practical example
  5. Why self-service works
  6. An article works at night too
  7. Customers want autonomy
  8. How to structure an effective knowledge base
  9. 1. Clear categories
  10. 2. Titles that answer questions
  11. 3. Actionable content
  12. 4. Effective search
  13. 5. Feedback on content
  14. Content types for the knowledge base
  15. 1. Articles (guides)
  16. 2. FAQs
  17. 3. Tutorials
  18. 4. Glossary
  19. 5. Downloads
  20. 6. Videos
  21. How to create content that works
  22. Start from real questions
  23. Write for someone who knows nothing
  24. Update regularly
  25. Self-service portal: the essentials
  26. 1. A clean homepage
  27. 2. Consistent branding
  28. 3. Readable on a phone
  29. 4. Access to human support
  30. 5. A personal ticket area
  31. Metrics to monitor
  32. Searches that end in an article
  33. The verdict on individual articles
  34. Fewer tickets on one question
  35. Searches that lead nowhere
  36. Common mistakes to avoid
  37. 1. A hidden KB
  38. 2. Too much content, too little quality
  39. 3. Language that is too technical
  40. 4. No updates
  41. 5. Search that does not work
  42. From nothing to your first articles
  43. First step: collect the questions
  44. Second step: write
  45. Third step: the portal
  46. Fourth step: an internal run
  47. Fifth step: publish
  48. Conclusion

An effective knowledge base is not an archive of FAQs. It is part of the customer service operation: it intercepts questions before they become tickets, provides consistent answers outside business hours and gives agents a shared source during conversations.

That requires content architecture, search, editorial governance and a portal designed around customer intent. This guide explains how to put those elements in place.

What is a knowledge base?

A knowledge base (KB) is a digital library of articles, guides and FAQs that answers your customers' most frequent questions.

It brings together public customer content and internal team procedures in one governed environment.

The two types of knowledge base

1. Internal knowledge base (for the team)

  • Operating procedures
  • Response scripts
  • Technical guides
  • Notes on edge cases

It helps the team answer faster and more consistently.

2. External knowledge base (for customers)

  • Public FAQs
  • Product usage guides
  • Step-by-step tutorials
  • Glossary of terms

It lets customers find answers without contacting you.

What is a self-service portal?

The self-service portal is the public interface where customers reach the knowledge base and can:

  • Search articles and guides
  • Browse FAQs
  • Download documentation
  • Open a ticket (if they cannot find an answer)
  • See the status of their requests

It is your company's help centre, reachable at any hour. In Uppo it is the self-service portal, with custom domain options depending on your plan and configuration.

A practical example

  1. A customer has a problem at 11pm
  2. They visit your self-service portal
  3. They search for "product return"
  4. They find the article "How to make a return in 3 steps"
  5. They follow the instructions and solve it themselves
  6. They did not have to wait for a support reply

The result: the customer has solved it, and nothing reached the team.

Why self-service works

An article works at night too

An answer written once stays available at any hour, for anyone, with nobody on a night shift. It is the part of support that carries growth without adding people: the same lever that appears among the seven in how to reduce response times.

Customers want autonomy

Today's customer:

  • Is used to searching on Google
  • Does not want to wait in a queue
  • Prefers to solve things alone where possible
  • Contacts support only for complex problems

Offering self-service is not "abandoning" the customer, it is respecting their time.

How to structure an effective knowledge base

1. Clear categories

Organise content logically:

📁 Getting started
   ├── Creating an account
   ├── First sign-in
   └── Initial setup

📁 Payments and invoicing
   ├── Payment methods
   ├── Invoices and receipts
   └── Changing plan

📁 Shipping and returns
   ├── Delivery times
   ├── Tracking an order
   └── Making a return

📁 Technical problems
   ├── Forgotten password
   ├── Common errors
   └── Contacting support

2. Titles that answer questions

Wrong:

  • "Shipping"
  • "Account"
  • "Payments"

Right:

  • "How long does delivery take?"
  • "How do I create an account?"
  • "Which payment methods do you accept?"

Titles should be the questions customers search for on Google.

3. Actionable content

Every article must answer a specific question with clear instructions:

Recommended structure:

  1. Short answer (1-2 sentences) visible straight away
  2. Detailed steps, numbered
  3. Screenshots where useful
  4. Notes and warnings for edge cases
  5. Related links to other articles

Example:

How to reset your password

You can reset your password from the login page by clicking "Forgotten password".

Steps:

  1. Go to login.example.com
  2. Click "Forgotten password"
  3. Enter your email address
  4. Check your inbox (spam folder too)
  5. Click the link in the message
  6. Choose a new password

Note: the link expires after 24 hours.

Related articles:

  • How to change the account email address
  • Login problems

A KB is useless if customers cannot find what they are looking for.

What the search has to do:

  • look inside the text, not just the titles
  • suggest as you type
  • understand synonyms: "return", "send back", "refund request"
  • order results by relevance

When search stops chasing the exact word and starts looking for meaning, that is AI: what works and what does not is in AI in customer support.

5. Feedback on content

Add to every article:

"Was this article helpful?" Yes No

If many say "No", the article needs improving.

Content types for the knowledge base

1. Articles (guides)

Long, detailed content on specific topics.

When to use them:

  • Complex procedures
  • Configuration guides
  • Best practices

2. FAQs

Short, direct questions and answers.

When to use them:

  • Questions with a one-line answer ("How much does it cost?")
  • Common pre-purchase doubts
  • Quick information

3. Tutorials

Step-by-step guides with screenshots or video.

When to use them:

  • Onboarding new users
  • Complex features
  • Visual procedures

4. Glossary

Definitions of technical or industry-specific terms.

When to use it:

  • Technical products
  • Sectors with their own jargon
  • Avoiding confusion over terminology

Some helpdesks highlight glossary terms inside articles on their own, showing the definition on hover.

5. Downloads

Downloadable files: manuals, forms, templates.

When to use them:

  • Technical documentation in PDF
  • Forms to fill in
  • Templates and resources

6. Videos

Video tutorials for complex procedures.

When to use them:

  • Product demonstrations
  • Guided setup
  • Visual explanations

How to create content that works

Start from real questions

Do not invent the articles. Analyse:

  1. Past tickets: which questions come up again and again?
  2. Failed searches: what are customers looking for without finding an answer?
  3. Support team: which questions bore them the most?
  4. Competitors: what do they cover in their KBs?

Write for someone who knows nothing

  • Avoid technical jargon (or explain it)
  • Assume zero knowledge of the product
  • Use short sentences and bullet lists
  • Add screenshots for every step

Update regularly

A knowledge base that is out of date is worse than one that does not exist: it sends the customer to do something that no longer works.

What to review, and when:

  • after every release, the articles the change touched
  • every month, the articles collecting the most "this did not help"
  • content that is no longer needed: archive it
  • new questions that keep coming back: write the article

Self-service portal: the essentials

1. A clean homepage

  • A prominent search bar
  • Main categories visible
  • Most read and most useful articles
  • Quick access to human support

2. Consistent branding

The portal must look like part of your site:

  • Company logo
  • Brand colours
  • The same visual style
  • A custom domain (help.yourdomain.com)

3. Readable on a phone

Many people arrive from a smartphone. The portal has to fit the screen, keep the text readable without zooming, and offer a search you can use with a thumb.

4. Access to human support

If self-service is not enough, contacting a human must be easy:

  • A "Contact us" button always visible
  • A form pre-filled with context
  • a website chat, if you use one

5. A personal ticket area

If the customer has an account:

  • See their own open tickets
  • Check the status
  • Add information
  • Review the history of past requests

Metrics to monitor

Searches that end in an article

Searches with a click on an article / total searches × 100

There is no threshold that holds for everyone: what counts is the comparison with your own previous month. If the number falls, the content is not answering the questions people are typing.

The verdict on individual articles

"Helpful" ratings / total ratings × 100

Look at it per article, not as an average: the average hides exactly the ones that need rewriting. The articles at the bottom are your to-do list.

Fewer tickets on one question

(Tickets before the article − tickets after) / tickets before × 100

Measure it on a single recurring question, not on the total: the total contains too much else to credit one article with the change.

Searches that lead nowhere

Searches with no results can reveal topics to cover or terms to add to your content. A search that returns results but receives no clicks is a different signal and should be analysed separately.

Common mistakes to avoid

1. A hidden KB

If customers cannot find it, they will not use it.

What to do: a link in the site header, in confirmation emails and in the account area.

2. Too much content, too little quality

A few articles written well are worth more than many written in a hurry: the hurried ones contradict each other and nobody notices.

What to do: start from the questions you genuinely receive most often, taken from your own tickets, and stop there until those are properly covered.

3. Language that is too technical

"Provision the account" → "Create the account"

What to do: have someone who does not know the product read it back.

4. No updates

Instructions that point at a button which no longer exists.

What to do: set a review on a fixed schedule and put it in the calendar, or it will not happen.

5. Search that does not work

The customer searches for "return" and finds nothing because the article is called "Refund policy".

What to do: add the synonyms, and run the searches yourself, using the words a customer would use.

From nothing to your first articles

First step: collect the questions

  • export the tickets from the last few months
  • pull out the questions that repeat
  • group them by category

Second step: write

  • begin with the most frequent questions
  • use the same structure every time: short answer, then the steps, then the exceptions
  • add images where they genuinely help

Third step: the portal

  • create the categories
  • publish the articles
  • set the branding and the domain
  • test the search with the customers' own words

Fourth step: an internal run

  • let the team use it before customers do
  • collect their objections
  • fix what stands out immediately

Fifth step: publish

  • put the links on the site and in your emails
  • tell your customers
  • look at the searches with no results, every week

Conclusion

A knowledge base does four things: it takes the repeating questions off the team, it gives the customer an answer when the office is shut, it grows without extra people, and it makes sure everyone gets the same correct answer.

The moment to start is before the volume becomes unmanageable, not after. And if you are still choosing the tool to build it with, the items to check are in the checklist for choosing the right helpdesk.

Uppo

Turn the method into customer service that works.

Centralise conversations, assign clear ownership and keep response times and quality under control from one helpdesk.

Start your free trial Talk to the team