Running a knowledge base with 600+ articles for a SaaS product

I think of a knowledge base as the brain of a product. It helps customers find solutions, gives support staff reliable guidance and provides information for the company’s AI to use when answering questions.

But having an answer in the knowledge base does not always mean someone can use it.

They find the article. They read the steps. Then they reach a condition that does not quite match their situation. Does this apply to their plan? Does that number mean contacts or messages? Is the review still happening, or has the status simply failed to update?

Good knowledge base work means preventing that confusion before it happens, making sure people can find the answer easily, understand the conditions and act without getting stuck.

What I owned

I independently built and maintained more than 600 articles for customers and a support team of 100–200 staff. I:

• Wrote setup guides, explanations, FAQs and troubleshooting articles.
• Organised categories, titles and links between related articles.
• Set a standard structure and writing style.
• Explained conditions and exceptions with examples.
• Updated affected articles when a product, policy or workflow changed.

AI can help draft and summarise text. I still need to decide what is missing, where the answer belongs and what could lead a reader to make a mistake. Those decisions start with the problems people encounter while using the product and doing their work.

Deciding what needs to change

I found gaps through questions from customers and support staff, bug reports, tasks that slowed the team down and repetitive work.

When staff could not find an answer or questioned an existing article, I reviewed the guidance. When customers repeatedly asked something the knowledge base did not explain, I added the missing information or a way to handle that situation.

The response depended on the problem. Missing information might need a new article. An existing answer might need a clearer title, a better category, a related link or an example explaining the exception.

Colleagues also brought me problems they found while helping customers. Three examples, with details changed:

• A title that pointed to the wrong product. An article about placing Google AdSense on a site used “Ads” in the title. A colleague pointed out that Google Ads is for paying to advertise, while AdSense is how site owners earn from ads. I renamed the article. It was also missing a step: after turning on Auto Ads, the reader still needs to add the AdSense code to the site header. I added that step.
• A workaround nobody had written down. A customer wanted a button that downloads a PDF instead of opening it in a viewer. Support had said this was not supported. A direct download link format for Google Drive files did the job, so I added it to the guidance.
• A fix that did not work. An article suggested a robots.txt rule to remove a page from search results. A colleague showed on a live site that the page stayed in the sitemap and could still appear in results. I rewrote the guidance around what works: Google’s removal tool, deleting the content or adding a password to it, and using robots.txt only to stop crawling.

Sometimes the task itself needed to change. Staff searched the knowledge base frequently, so I showed them shortcuts to make searching easier. When copying chat records involved repetitive work, I built a tool to copy them with one click. I then documented how to use the tool.

The knowledge base helped people use those improvements in their everyday work.

Writing from the reader’s point of view

Once I knew what needed explaining, I worked through the task myself, step by step. I checked where a reader might hesitate and what different choices or buttons would do.

I made instructions specific enough to follow. Alongside the button label, I described where to find it, such as the menu in the left sidebar. I used plain language, lists for steps and tables for comparisons. Where a direct link could take readers to the right place, I included it.

I used screenshots where a setting or action might be difficult to locate. I also considered maintenance: screenshots can become outdated when the interface changes, so I used them where they added useful guidance rather than at every step.

These choices helped me address four questions: Does this apply to me? What should I do? How do I know it worked? What if my situation is different?

Adapted examples. Wording and product details have been changed for confidentiality.

Explaining usage and billing rules

In a plan guide, I explained the difference between the number of active contacts and the number of messages. A definition alone could leave readers unsure whether repeated activity counted again or what happened in a new month.

I used scenarios to show how the rule applied. For example, a simplified rule might count each contact once per calendar month:

The example separates the number of contacts from the number of messages and shows when the counting period changes.

I also explained exceptions that could change the answer, such as what happens when an allowance is reached, which fees are returned after a refund, or how a regional restriction affects the available options.

Turning troubleshooting into decisions

When a publishing status appeared stuck, several different situations could produce a similar question. I explained how to distinguish them and what to do next.

When an issue needed investigation, I listed the relevant information to send to support, such as the account email, page URL and error screenshot. This gave readers a concrete next step and explained what staff needed to investigate.

Making technical instructions easier to follow

In domain setup guides, I separated actions by the system where they needed to happen. I explained which values belonged to the reader’s own site, distinguished those values from examples, and included checks for an unsuccessful connection. This helped make the handoff between systems explicit.

Keeping related content current

When a product or rule changed, I checked where the same information appeared across the library. A plan rule could be explained in an overview, used in a calculation example and repeated in a FAQ.

My approach was to:

1. Clarify what changed and which users or situations were affected.
2. Check the main article and related guides, examples and internal instructions.
3. Update the conditions, steps and examples affected by the change.
4. Read the related explanations together to check that they gave the same answer.

Categories, consistent titles and links helped connect those articles. The structure also needed to help readers move from a general explanation to the setup or troubleshooting guidance relevant to their question.

Checking the update

I use the original question or scenario to check an edit: does the revised article now explain what the reader needs to know and do? For a rule, that means checking the conditions and examples. For a procedure, it means checking the sequence, expected result and next step if something goes wrong.

An update can pass those checks and still need improvement. If the same question returns, I look again at whether the answer is easy to find and whether the explanation covers the situation people are actually facing.

Preparing knowledge for AI

The company’s AI needed clear source information to answer questions. My responsibility was the knowledge content: definitions, conditions, exceptions and examples that explained how the rules applied.

I wanted the relevant conditions to be explicit in the source text. For a usage question, the limit alone is incomplete without the plan, what counts towards usage and the counting period. I kept those details together so the content explained the rule in context.

Consistency mattered here too. If an overview and a FAQ gave different answers, I checked both against the current rule and updated the affected explanations.

One example: the AI kept confusing affiliates and resellers. I treated this as a content problem. The difference had to be written down, not left for the AI to work out. I:

• put the two terms side by side in one place, covering who has the relationship with the customer, who collects payment, who supports the customer and how each earns money
• checked other articles for loose wording such as “partner” or “agent”, so each term meant only one thing
• gave each term a scenario and a simple rule for telling them apart
• asked the AI the original question again to check whether the answer had changed

What the work delivered

The library brought together product explanations, practical setup guides and troubleshooting paths for customers and support staff. My ownership covered deciding what needed to be documented, writing guidance people could follow and keeping related content consistent through updates.

I assess the work with three questions:

1. Can readers find the answer?
2. Can they understand how it applies to their situation?
3. Can they trust that it is current?