Xilnex Compass — Writing KB Articles Compass Can Answer From

If you read nothing else

1Use the editor's Heading 1 / Heading 2 styles. Not bold text.

2Type every step out. Compass cannot read your screenshots.

3Upload screenshots into the editor. Never paste from Lark or Drive.

4Put the answer in the first line of each section.

5Delete empty sections and "TBC" placeholders before publishing.

Copy a template to start from

Paste one into a new Zoho article and fill in the [square brackets]. Each one is already shaped the way Compass reads best — headings in the right places, the answer up front, nothing hiding in a screenshot.

A · How-to setup, configuration, "how do I…"

# How to [do the thing] in [Xilnex Classic / Portal / POS / Mobility]

## What this is for
[One sentence: who needs this, and when.]

## Before you start
- Access needed: [role or portal permission]
- Applies to: [module / version / outlet type]

## Steps
1. Go to [Menu] > [Submenu] > [Screen].
2. Set [Field] to [Value].
3. Click [Button].
   [Screenshot here — and write in text what the reader should see.]
4. Confirm [what success looks like on screen].

## If it doesn't work
- [Symptom] — check [the thing to check].

## Related
- [Title of another KB article]

B · Troubleshooting an error, a failure, "why is this happening"

# [Exact error message or code] — [what it means in plain words]

## Symptom
[What the user sees, in their words. Paste the exact error text — this is
what people search for.]

## Cause
[Why it happens.]

## Fix
1. [Step]
2. [Step]
3. Confirm [how you know it worked].

## If the fix doesn't hold
Escalate to [team] with: [logs / screenshot / ticket reference].

C · Rule or policy limits, pricing, "what happens if…"

# [Feature or policy name]

## The rule
[State it in one sentence. This is the line Compass will quote.]

## Cases
- [Case]: [outcome]
- [Case]: [outcome]
- [Case]: [outcome]

## Common questions
**Q: [Question, in the words people actually ask]?**
A: [Answer.]

## What this does not cover
[Scope boundary — where this rule stops applying.]

Writing a Master FAQ entry instead? Use template C, but make the heading the question itself — "## Why is my sales file missing for one outlet?". One question per heading; Compass stores each entry separately.

The same article, before and after

Nothing was researched or added here — the content is identical. Only the shape changed, and that alone decides whether Compass can answer from it.

✗ Before — one blob, steps in the images

Resend Sales File

Please refer to the tools in the link below.

[Lark file link]

SCENARIO 1
Missing sales file.
See screenshots below for the steps.

[screenshot]
[screenshot]
[screenshot]

SCENARIO 3
STEPS
-
-
-

✓ After — real headings, steps in text

# How to resend a sales file for Mall
Integration

## Missing sales file for a date range
1. In the server, get the service name
   from xis.mallintegration_config.
2. Run Mall Integration Internal Tools.
3. Select the date range and file
   type A.
4. Click Generate File, then Upload.
   [screenshot: the Upload button turns
   green when the file is accepted]
5. Check the sales log in
   C:\Xilnex\Mall_Integration.

## If the log shows an error
Escalate to the Mall Integration PIC
with the sales log.

What changed: bold text became real headings, so each scenario is its own retrievable passage · the steps were typed out instead of left in screenshots · the screenshot got a caption · the tool link stayed but no longer carries the whole answer · the empty SCENARIO 3 block was deleted.

1 How Compass actually reads your article

It never reads top-to-bottom. It slices your article, then picks the best few slices from across the whole knowledge base.

Your article is split into passages of ~300 words, overlapping slightly so a sentence on a boundary isn't lost.

Compass searches every passage of every article and keeps only the best 5.

The answer is written from those 5 passages only — not from your full article.

Three consequences shape everything else in this guide. A passage is judged alone, so a step that only makes sense after the section above it will be answered wrongly. Headings start new passages, so they are real structure, not decoration. And your article competes with roughly 950 other passages — accuracy alone doesn't win; matching how people actually ask does.

2 What Compass can and cannot see

If you only remember one section, remember this one.

In your article	Searchable?	What Compass does with it
Body text, headings, bullets, numbered lists	✓	Read and searched — answers are built from this
Screenshots & images	✗	Shown to the reader, but never read. Compass cannot extract text from a picture
Image alt text	✗	Used only for accessibility — it will never help anyone find your article
Tables	partly	The words in the cells survive; the row/column grid is lost
Links (Lark files, portals, other sites)	✗	The link text is read; whatever it points to is invisible
File attachments on the article	✗	Not picked up at all
Articles in Draft or Review	✗	Only Published articles reach Compass
Internal, agent-only articles	✓	Ingested normally — see section 9

The single most common failure: the steps live inside the screenshots, and the text around them just says "refer to the screenshot below." Compass then answers with almost nothing and shows some pictures. Every step needs a text line, even when a screenshot also shows it.

3 Use real headings, not big bold text

This is the cheapest, highest-impact fix available in the KB today — about a minute per article.

✗ Bold text pretending to be a heading

Step 1 — Configure the formula
To Compass this is ordinary body text. The article becomes one undivided blob, so it gets cut at arbitrary points and a retrieved passage often starts mid-procedure.

✓ The editor's Heading style

Use the Zoho editor's Heading 1 / Heading 2 dropdown. Compass treats it as a real section boundary, so the section stays whole and the heading tells Compass what it's about.

Where we stand today: 120 of 310 published articles contain no real headings at all — held together by bold text alone. If you own any of them, converting the bold pseudo-headings to real Heading styles will measurably improve how well they answer.

Tip: In a Master FAQ entry or an HR markdown file, # and ## do exactly the same job.

4 Upload screenshots into the Zoho editor

Screenshots do appear in Compass answers — but only when Zoho is hosting them.

✓ Upload it into the article

Drag-and-drop the image file, or use the editor's image button, so Zoho stores it on support.xilnex.com. This is how the images that work today are stored.

✗ Paste from Lark, Drive, or a web search

A pasted image still points at that other place. Those links are temporary or login-restricted: they render for you and are broken for everyone else — readers, agents, the portal, and Compass.

This is happening right now. 1,434 of 1,470 images in the KB are correctly hosted by Zoho and work fine. The other 36 images across 12 articles point at Lark or a web search and are invisible in Compass — worst affected: Creating Task for Mobility in Xilnex Portal (12), How to use replenishment module (7), Creating a Reminder Task Type (4). If one is yours, please re-upload those screenshots directly into the editor.

Caption every screenshot. Write what the reader should see or do, in text, beside the image — "Set Reorder Point Formula to Formula 2" beats "as shown below." That caption is the part Compass can search. Answers show at most 6 images per passage, so a few decisive screenshots beat a dozen near-identical ones.

5 Tables keep their words but lose their grid

A table's meaning usually lives in the row/column relationship — and that relationship does not survive.

Risky on its own

Plan	Outlets	Price
Basic	1	RM99
Pro	5	RM299

Add this underneath

Basic: 1 outlet, RM99/month.
Pro: up to 5 outlets, RM299/month.

Keep the table for humans; add the bullets for Compass. Without them, a value can get separated from the row it belonged to and produce a confidently wrong answer. A document-history table at the top of an article is fine to keep — it just isn't an answer.

Don't paste an SOP straight from Word. Word carries layout markup that becomes a large amount of empty space, which dilutes how well your article matches a question — 22 of our 76 internal articles are affected. Paste as plain text, then re-apply headings and bullets in the editor.

6 Never leave empty scaffolding

A heading with nothing under it is worse than no heading — it looks like Compass found the answer, then says nothing.

A real example from our KB

SCENARIO 3
STEPS
-
-
-

SCENARIO 4
STEPS
-

Either fill it in, or delete it until you're ready to write it. The same goes for "TBC", "to be updated", and blank template rows. Placeholder sections get retrieved and cited exactly like real content.

An article that is almost entirely empty (under about 30 characters of text) is rejected outright and never reaches Compass at all.

7 Write so each passage stands alone

Because Compass may retrieve one section and nothing around it.

✗ Depends on its neighbours

"Follow the steps above, then configure the settings mentioned in the previous section."

Retrieved on its own, this tells the reader nothing.

✓ Self-contained

"To set up loyalty points, go to Settings > Loyalty > Point Rules and configure the earning rate."

✗ Buries the answer

"In the early days of Xilnex we had a different approach to refunds… after much deliberation, the current policy is: refunds within 30 days."

✓ Front-loads the answer

"Refunds must be processed within 30 days of the original transaction. The refund goes back to the original payment method."

✗ Doesn't use the asker's words

Feature X — "Enable it in Settings > Advanced."

Nobody searches for this phrasing.

✓ Contains the question

How to Enable Feature X — "To enable Feature X, go to Settings > Advanced > Feature X and toggle it on."

Also: keep one topic per paragraph, prefer bullets over prose for lists, give sections descriptive names ("Troubleshooting: POS Offline Mode", not "Notes" or "Misc"), and avoid "it", "this" and "the above" without saying what you mean. A good title matters most of all — include the error text or the words a colleague would type.

8 Publishing, renaming and removing Navigator

Only Published articles reach Compass. Draft and Review are invisible.

When will it appear? Compass re-syncs the Zoho KB every night at 02:15 (MYT), so a newly published article is normally answerable the next morning.
Need it live now? A Navigator can use Insert Zoho KB link in the Resolution Queue and paste the article link. That pulls it in immediately and re-checks any open question it answers. Either the portal link or the link from the agent console works.
Editing is safe. Edit and re-publish freely — the nightly sync notices the change and replaces that article's content.

Known limitation — please tell the Compass admin if you do either of these.
• Renaming a published article's title currently makes Compass treat it as a brand-new article and keep the old version too. Both then answer, and readers may get the outdated one.
• Unpublishing or deleting in Zoho does not remove it from Compass — it keeps answering from content you've retired.
A short message after a rename or a retirement is enough until this is handled automatically.

9 Internal and public articles both work

Writing an internal, agent-only article is a perfectly good way to close a knowledge gap — nothing needs to be made public for Compass to use it.

Assume any colleague may read it

Everyone using Compass is Xilnex staff, so content from an internal article can surface for a colleague in another team. Don't put anything in the KB you wouldn't want them to read — and never credentials or customer PII, in either tier.

Make the article self-sufficient

The "read the source" link on an answer citing an internal article doesn't open for people who aren't signed into Zoho as an agent. Write so the answer itself is complete, rather than relying on the reader opening the source.

Prefixing an internal article's title with AGENT | — as many already do — is a helpful convention: it tells a reader at a glance which tier an answer came from.

10 Before you hit Publish

Ten seconds of checking saves a question that Compass answers badly for months.

☐ Is the article Published — not Draft or Review?

☐ Does the title contain the words someone would actually search for?

☐ Is every step written in text, not only shown in a screenshot?

☐ Were all screenshots uploaded into the editor (not pasted from Lark, Drive or a web search)?

☐ Does each screenshot have a caption saying what to do?

☐ Are section headings real Heading styles, not bold text?

☐ If there's a table, is the rule it encodes also written as bullets?

☐ Any empty sections, "TBC" placeholders or blank template rows left over?

☐ Does each section make sense on its own, without the one above it?

☐ Did I avoid vague references like "as mentioned above"?

☐ Is the answer complete in the article itself, rather than behind a link?

☐ Any credentials, API keys or customer PII to remove?

That's it. Publish, and Compass picks it up tonight — or ask a Navigator to insert the link if someone is waiting on the answer today.