How We Built the Widget (And What We Got Wrong)

I’ve written before about why I think our widget is one of the best in the business. This is the other side of that. The bits we got wrong on the way, and the one thing that still isn’t done. Building in public only counts if you include the parts that make you wince.

For anyone new to it: the widget is how KnowledgeScout shows up where people actually work. A panel or a chat bubble you drop into a website, a CRM, an internal portal. Your team or your customers get answers from your knowledge base without opening another tab. Simple idea. The build was less simple.

We shipped it too thin at first

The first version rendered plain text and not much else. You asked a question, you got a clean paragraph back. It looked tidy in a demo.

The problem showed up the moment real content went through it. A knowledge base article isn’t a paragraph. It’s a table of rate tiers, a screenshot with the right button circled, a step with an image showing exactly which screen you should be on. Our early widget flattened all of that. The table became a run-on sentence. The screenshot vanished. People were getting an answer that was technically right and practically useless, because half the meaning lived in the formatting we’d stripped out.

So we went back and made the widget render the real thing. Tables come through as tables. Inline images show up as images. The most recent piece, and the one I’m quietly proudest of, is that an answer can now bring the actual picture from your content back to you, not a description of it. That took far longer than it should have, because we shipped the easy version first and had to learn why it wasn’t enough.

The bug I’m least proud of

For a while, certain article types could show content that wasn’t theirs. The short version: when we rendered the non-standard formats, old leftover sections from a previous state could leak into what the widget displayed. Nobody’s data crossed between companies, to be clear. But within one knowledge base, a reader could occasionally see a fragment that shouldn’t have been on that article.

We found it, we fixed it, and we added a rule that the widget returns nothing rather than risk rendering the wrong thing. That’s the lesson that stuck: for a tool whose entire job is being trusted, showing nothing is always better than showing something that might be wrong. A blank space makes people ask. A confident wrong answer doesn’t.

The part we still haven’t finished

Here’s the one that’s genuinely not done. Quizzes don’t run inside the widget yet.

We have quizzes in the product, and they matter, especially for teams that need to prove someone understood a policy rather than just clicked past it. But right now, if a reader hits a quiz from the widget, it opens the full app instead of running in place. Workflows render inline. Slideshows render inline. Quizzes still bounce you out. That’s on us, and it’s on the list.

I could have left that out of this post. But if I’m going to tell you the widget renders your interactive content, you deserve to know which piece doesn’t yet. It will. It isn’t today.

The decisions I’d make again

Not everything was a mistake. A couple of calls I’d repeat.

We used a proper modern auth standard for the internal widget instead of a simple shared key. It was more work to build and it’s more work to set up. It’s also the reason I can look a security team in the eye when they ask how the widget knows who someone is. For the kind of teams we’re building for, that trade was obvious.

And we chose to make the widget domain-locked and email-gated from the start, rather than bolting security on later. Retrofitting that is miserable. Building it in from day one meant a slower launch and a product I don’t have to apologise for.

Why tell you any of this

Because the version of building in public where everything went perfectly is a marketing post wearing a hoodie. The real thing is messier, and I think the mess is the interesting part. We shipped a widget too thin, found a bug that embarrassed me, and there’s still a feature I’m promising you rather than showing you.

If you want to see where it’s got to, and where it hasn’t, the best way is to put it on your own content and poke at it. You’ll find the good parts fast. And if you find something we got wrong that I haven’t listed here, genuinely, tell me. That’s how the last round of fixes happened.

The KnowledgeScout Team