Best practices for structuring 'Knowledge Articles'

Overview

As the world embraces enterprise knowledge automation, it is crucial for organisations to structure their information in a way that is easily understood by the assistant and clear to end users.

Leena AI has therefore compiled a set of best practices for creating effective knowledge articles. The following guidelines apply across various platforms, including SharePoint, Confluence, and Leena KM.

The guiding principle is simplicity and clarity: content that is easy for a person to read in a simple document is generally the easiest for the assistant to interpret accurately.

Clear Article Title

For a knowledge article to be truly effective, its title must immediately convey its content and purpose. Employees often rely on the title to decide whether an article is relevant, so a vague title like "Other FAQ" can leave them unsure of its subject.

In contrast, a title such as "Employee Onboarding FAQs" clearly indicates that the article addresses common questions related to onboarding, making it more accessible and useful.

Clear Article Path

Grouping related articles within the same folder improves structural clarity and simplifies navigation.

Example: By consolidating all leave-related articles into a dedicated folder titled "Leave," users can easily locate all pertinent information, improving their overall experience.

Structure Content in Clear Pointers

Organising information using clear paragraphs, bullet points, and appropriate line breaks significantly improves readability and comprehension. Standard formatting — headings, bullet points, and numbered lists — also helps the assistant recognise the hierarchy and context of the information, leading to more relevant answers.

In contrast to a single long paragraph that merges every detail together, a clear structure ensures that users can navigate the information and understand each step.

Example of good structure:

To download Microsoft Teams, follow these steps:

Desktop version:

Step 1 - Visit the official Microsoft Teams download page.

Step 2 - Choose the appropriate version for your operating system (Windows or Mac).

Step 3 - Download the installer and run it.

Mobile version:

Step 1 - Open the Google Play Store (for Android) or the Apple App Store (for iOS).

Step 2 - Search for "Microsoft Teams" and tap the install button.

After installation:

Step 1 - Launch the application.

Step 2 - Sign in using your Microsoft account or organisational credentials.

A note on numbered lists

Numbering that comes from a document's automatic list formatting is not reliably preserved - numbered items may be read back as plain bullets. The order of the items is kept; the numbers themselves may not be.

Where the sequence carries meaning - steps in a procedure, ranked criteria, clause or policy references - write the number into the text of the line itself:

Instead of relying on auto-numbering, type "Step 1 - Visit the official download page".
For referenceable clauses, type "4.2 Notice period" as part of the heading or line.

Numbers typed as part of the text are read as ordinary content and are always retained.

Limitation on check boxes: We are unable to retain the checkbox icon and hence the selected/unselected state of the checkboxes as well. Please ensure if the state of the checkbox signifies a meaning, the same should be translated to text as well.

Use a Single-Column, Linear Layout

Content is read from top to bottom in a single flow, so a straightforward single-column layout keeps sentences and their context together.

Multi-column layouts (like a newsletter), text boxes, and content placed in headers or footers can disrupt this flow and cause text to be read out of order. Keep critical information in the main body of the document.

Tables

Tables are interpreted well when they are kept simple, and the simpler the table, the more reliably it is read.

Works best:

Clear headers and uniform rows: Tables with explicit, consistently formatted column headers and uniform rows help preserve context.
Plain, standard tables: Tables in plain text or standard formats, where each cell contains a single, distinct value.

Use with care:

Complex layouts: Tables with merged cells or multi-level headers can usually still be interpreted, but a simpler layout gives more reliable results.
Tables as images: Avoid saving a table as an image, and avoid tables that span multiple pages.
Large or calculation-heavy data: For data that users will filter or calculate over, provide a CSV or Excel file rather than a table embedded inside a document. See Spreadsheets and Tabular Data below.

Images

Images that carry meaning — charts, diagrams, screenshots, flowcharts — are automatically analysed, and a description of their content is added to the article so they can be found in search. This makes the subject of an image findable in search — but the description summarises the image rather than transcribing it, so it is not a substitute for having the information in text.

To get the most value from images:

Use clear, high-quality images. Blurry or low-resolution images are harder to interpret accurately.
Add a short caption or description near each important image, summarising its key point. This improves how accurately the image is understood and guarantees the information is captured in text.
Type text out rather than embedding it as an image. A screenshot of a policy paragraph, for example, is read far less reliably than the same text typed into the article.
Don't worry about decorative images. Logos, icons, and similar decorative elements are ignored, so they do not need captions and will not affect search.

What to expect from images

The generated description captures what an image is about and its main points. It is not a character-by-character reading of the image, which means:

Text inside an image is not extracted word for word. Node labels, callouts, annotations and footnotes may be condensed into a single line or left out.
Tables inside an image are not read as tables. Individual row and column values are not extracted, so they cannot be looked up or calculated over.
Links inside an image are not captured. A URL that appears only inside an image will not appear in the article and will not be clickable in a response.
Dense diagrams lose the most. Mind maps, org charts, multi-level process flows and heavily annotated screenshots yield a high-level description; the detail beneath the top level is generally not retained.
Non-English text inside images is read less reliably than the same text typed into the article.

Why this matters: the description reads fluently and looks complete, so missing detail is not obvious when reviewing an article — an article can appear to cover a diagram thoroughly while none of the diagram's substance has been captured.

Treat images as supporting material, never as the only place a fact appears. If a fact needs to be answerable, type it into the article body as well as showing it in the diagram.

Spreadsheets and Tabular Data (CSV and Excel)

Spreadsheets are fully supported, and a well-structured spreadsheet can be especially powerful: the assistant can perform calculations and precise lookups against it — for example, "What is the average tenure of employees in the Seattle office?" or "How many laptops are assigned to the Finance team?"

A loosely structured sheet can still be searched by keyword, but it cannot be used for calculations or totals. Structuring your data cleanly is what unlocks this more capable behaviour.

Structure data like a simple table

Put clear, concise column headers in the very first row (e.g. "Employee Name", "Start Date", "Office Location"), and start the table in the first cell (A1).
Keep each column to a single, consistent type of value — dates in one column, numbers in another, text in another.
Avoid merged cells and blank header rows, and do not place titles, notes, or images inside the data range.

Use descriptive file and sheet names

Name files and sheets for their contents. 2025_Q3_Sales_by_Region.xlsx is far more useful than data_final_v2.xlsx, and sheets named "US Sales" and "EU Sales" are better than "Sheet1". These names help the assistant identify the right table for a question.

Keep one table per sheet

Place a single table on each sheet. If a workbook contains several distinct tables, split them onto separate sheets so each one is read cleanly.

When to expect keyword-only results

Very text-heavy sheets (long paragraphs inside cells) or irregular, transposed layouts are treated as searchable text rather than as a queryable table. If you expect users to ask questions that require totals, averages, or filtering, format the data as a clean table as described above.

Web Pages and Other HTML Sources

Articles that come from a web page or a web-based system — an intranet page, a portal, a CMS-published site — are read from the page's underlying markup rather than from what appears on screen. Text present in the page but not visible to a reader can still be indexed. This commonly includes:

navigation menus and mega-menus
the contents of inactive tabs and collapsed accordions
cookie and consent banners
template blocks holding placeholder text
"please enable JavaScript" messages
content hidden through styling or accessibility settings

Because this material is usually shared across an entire site, every article synced from that site inherits the same text. That makes distinct articles look similar to search, and in some cases the assistant can cite site furniture — a cookie banner, for example — as though it were policy.

Recommended

Scope your connector to the content areas of the site rather than syncing entire pages or entire sites, where the connector supports it.
Prefer page templates that keep the article body separate from navigation and promotional blocks.
Publish policy content as a document or a Leena KM article rather than as a heavily templated marketing page.
After the first sync, open a few articles and compare the Parsed content with the source page. Do not assume that what renders is what was indexed.

Include References and Links

Including references and external knowledge links in articles is recommended. It helps employees quickly access additional context and verify responses, improving the overall usefulness of the information provided.

Prefer Digital Text over Scanned Documents

Documents created digitally — saved from Word, Google Docs and similar tools — are read most accurately. The assistant can also read text from scanned pages and photographs, but accuracy varies, and there are specific cases worth checking before you upload.

Page orientation is not corrected automatically

Pages that are rotated, sideways or upside down in the source file are read exactly as they sit on the page. A rotated page does not come out unreadable — it comes out reversed: words in reverse order within each line, lines in reverse order within each block, and sections in reverse order down the page. The result looks like text, is stored as text, and is searchable, but it does not carry the document's meaning.

Before uploading, open the file and confirm every page is the right way up. Rotate any page that is not and save the change into the file — correcting the orientation only in your PDF viewer is not enough.

What else to check in a scan

Skew and perspective - Pages scanned crooked, and photographs taken at an angle, lose accuracy. Scan flat, or straighten the image before uploading.
Scan quality - Faint photocopies, speckled or noisy scans and low-resolution images all produce more errors. Aim for 300 DPI or better with good contrast.
Handwriting - Handwritten entries — signatures, filled-in fields, margin notes — are recognised inconsistently and should not be relied on for anything that must be answered accurately.
List numbering - Numbered lists in scans are especially likely to come back as plain bullets. See A note on numbered lists above.
Forms - Labels and their values are particularly prone to being separated in scanned forms.
Language - Accuracy varies by language and script; non-Latin scripts are read less reliably from a scan than the same text typed into an article.

The most reliable fix is upstream. If a digital original exists — the Word file the document was printed from, or the source PDF — upload that instead of the scan.

Use One Language per Article

Each article should be written in a single language. Avoid mixing multiple languages within the same article.

Content That Isn't Supported Yet

The assistant works with text-based content — documents, web pages, and spreadsheets. Audio and video files (such as recordings, webinars, and training videos) are not read today, so their contents cannot be answered from. If knowledge exists only in a recording, add a short written summary or transcript as the article so it can be found and used.

Password-Protected and Encrypted Files

Upload files that open without a password. A PDF that prompts for a password cannot be read: the article is still created, but it stays in Draft with no content in its body and cannot be sent for review. Re-parsing the same file will not help — the file itself has to be replaced with an unrestricted copy. The same applies to files carrying permission restrictions that block text extraction or copying, even where the file opens without prompting for a password.

A file-level password is not what keeps content private in Leena AI. Access to every article is controlled through audiences and folder permissions, so a password on the file adds no protection — it only prevents the content from being read.

If an article sits in Draft with an empty body after an upload or a connector sync, check whether the source file is password protected or permission restricted before raising it.

Document and Article Size

The most important guideline here is scope, not size: each article should cover a single, self-contained topic. When answering a question, the assistant pulls together the most relevant passages from across your knowledge base, so a focused article on one policy surfaces far more reliably than the same content buried inside a large, multi-topic handbook.

Recommended:

Keep each article focused on one topic or procedure. For most articles, a few pages is ideal.
If a document runs to many pages or covers several distinct topics, split it into separate, per-topic articles rather than uploading one large file. For example, break a full HR handbook into individual articles for leave, benefits, onboarding, and so on. As a rule of thumb, if a single document is growing beyond roughly 30–50 pages, it is usually covering more than one topic and is a good candidate for splitting.
Avoid the opposite extreme too: an article should still be self-contained enough to answer a question on its own, so don't fragment a single topic across many one-line articles.

Upper limits (avoid exceeding):

File size: Keep each PDF, Word, or PowerPoint file under 200 MB. For documents with complex tables, aim to stay under 100 MB.
Pages: Best to keep documents to 100 pages or fewer. However, we have a hard limit of 500 pages. Content beyond this is not read, so anything past the limit will not be searchable — and no error is shown when this happens.

Updated 4 days ago

Did this page help you?