Rewrite Articles for Findability and Chatbot Retrieval

Tier: Core · Workflow area: Knowledge management · ~30 minutes

This playbook rewrites existing, technically-correct articles so they get found: user-language titles and issue statements, synonym and error-string metadata, and chunk-friendly heading structure that keeps a retrieved fragment self-explanatory when a chatbot serves it out of context.

When to use

• Good articles nobody findsKB search analytics show zero-result queries for problems you know are documented under different words.
• Pre-chatbot preparationyou are about to index the KB for RAG (pb-38); retrieval quality is decided here, before a single embedding is computed.
• Post-audit cleanuppb-16 produced a keep-list; the survivors deserve the findability pass while they are already open.

When NOT to use

• On articles that fail the health auditrewriting a stale or contradictory article polishes a wrong answer. Correct first (pb-16), then rewrite.
• On admin-audience runbooksinternal procedures for technicians can and should stay in precise technical language; this pass is for user-facing and Tier-1 content.
• Vocabulary-only when structure is the problema 3,000-word article covering five issues needs splitting, not synonyms. Split it, then run this pass per article.

The recipe

1. 1.

   Harvest real user vocabulary. Pull 50–100 recent ticket subjects and search-log queries for the article's topic area. This is the ground truth of how your users describe the problem — "screen frozen", "email won't send", "vpn thing broken" — and it beats any brainstormed synonym list.

2. 2.

   Run the rewrite prompt per article.

   Copy

   Rewrite this KB article for findability. Audience: end users and
   Tier-1 techs. Keep every technical fact, value and step EXACTLY as
   written — you are changing packaging, not content.
   
   Produce:
   1. New title: the symptom in user words (under 70 chars), e.g.
      "Wi-Fi keeps disconnecting on laptops" not protocol jargon.
   2. Issue statement: 2–3 sentences in user vocabulary, including the
      exact error text users see, in quotes.
   3. Restructured body with headings so every section stands alone:
      each heading names the article topic + the section purpose
      ("Wi-Fi disconnects — fix for Windows laptops", not "Fix").
      Sections under ~300 words each.
   4. Synonym/keyword block: 10–15 terms — user phrasings from the
      list below, error strings, product names old and new.
   5. Anything ambiguous or possibly outdated: flag as [CHECK], do
      not silently modernize.
   
   Real user phrasings for this topic: [paste harvested subjects/queries]
   Article: [paste]
   

3. 3.

   Check the chunk test. RAG systems retrieve fragments, not whole articles. Read each rewritten section alone and ask: if a chatbot showed only this section, would a user know what it is about and what to do? A passing section looks like:

   Copy

   ## Wi-Fi keeps disconnecting — fix for Windows laptops (step 2 of 3:
   forget and re-add the network)
   On the affected laptop: Settings > Network & internet > Wi-Fi >
   Manage known networks. Select "CORP-WLAN", choose Forget...
   

   The heading carries the symptom, platform and step position — retrieval-safe. A section headed just "Next steps" fails.

4. 4.

   Front-load the error strings. Exact on-screen error text ("The connection was refused", error codes, dialog titles) goes into the Issue statement and keywords verbatim, in quotes. Users paste error text into search boxes and chatbots; verbatim strings are the highest-precision retrieval keys you have.

5. 5.

   Apply metadata in the platform. Put the synonym block into the KB platform's actual metadata fields (keywords, search tags, alternate titles) — not just the article body. In ServiceNow, that is the keywords field plus knowledge blocks where used; in other platforms, labels/tags. A synonym list living only in body text helps full-text search but wastes structured-field boosts.

6. 6.

   Verify with real searches. Take five harvested user phrasings, run them through KB search (and the chatbot, if live), confirm the rewritten article now ranks. Before/after screenshots of the search results make this playbook's value visible to management in one image.

7. 7.

   Fold the rules into the factory. Update the pb-15 generation prompt so new articles are born findable: user-language titles, error strings quoted, standalone headings. This playbook then becomes a shrinking backlog, not a treadmill.

Make it yours

• ServiceNow shopsearch analytics under Knowledge Management give you zero-result queries directly; prioritize articles whose topics show the highest zero-result volume.
• Chatbot-first shopafter rewriting, re-index and run your golden question set (pb-39) before and after; retrieval hit-rate delta is the honest measure of this pass.
• Multilingual deskrun step 2 once per language with locally-harvested phrasings rather than translating the English rewrite; user vocabulary does not translate literally ("net is not working" patterns differ by region and language).

Quality check

• Diff the technical content. Compare old and new: every command, path, value and step must survive verbatim. The rewrite prompt says packaging-only; verify it obeyed.
• [CHECK] flags resolved by a human. The model will notice possibly-stale steps while rewriting — route those to the pb-16 verdict process, do not let the rewrite silently "fix" them.
• Titles pass the hallway test. Read the new title to a non-IT colleague; if they cannot say what problem it solves, it is still jargon.
• One issue per article. If the rewrite prompt's output tries to grow sections for a second issue, split the article instead.