Zum Hauptinhalt springen

AI-friendly documentation

How to write and structure your organisation's documents so that an AI assistant can find the right answers in them.

Timo Tuomi

• Industry Insights • Lesezeit: 3 Minuten

AI-friendly documentation

Note! These guidelines are not a requirement or precondition for using TekstiAI’s services, as we can make use of many kinds of documentation. Their purpose is to help you optimise your own documentation and data for AI use in general.

One general rule of thumb is that AI assistants retrieve answers directly from the organisation’s own documents. With very long documents, they do not necessarily read them from beginning to end like a person would but pick out short excerpts of text based on the question. The more clearly and precisely the information is written, the better the answers the assistant gives. Pay attention to the following:

1. One topic, one document

  • Where possible, cover one clearly defined topic in each document, for example a single process, service or set of instructions.
  • Give the file a descriptive name (e.g. “Submitting a travel expense claim – guidelines 2026”), not “Memo_v3_final”.

2. Descriptive headings and a logical structure

  • Use the tool’s own heading styles (e.g. Word’s Heading 1, 2, 3, SharePoint page headings or markdown’s #, ##, ###), not just bold text. Structure helps the AI make sense of the content.
  • Write headings as questions or so that they describe the content: “Who approves a purchase?” is better than “General”. Start a long document with a short summary.

3. Sections that can be understood on their own

  • With long documents, the AI may read only individual paragraphs. Clear context always improves the answers regardless: for example, write “the travel expense claim is approved by the line manager”, not “it is approved by them”.
  • Avoid references to entirely separate documents (e.g. “see the travel policy for details”), as the AI may not find or connect them. Write the necessary information directly into the document. In long documents, also avoid references such as “as stated above” or “see the previous section” unless the point is briefly repeated.

4. Precision and unambiguity

  • Write out concrete details: names, roles, deadlines, amounts, units and contact details.
  • Spell out abbreviations and always use the same term for the same thing. Write separate guidelines for different cases rather than one set of guidelines with lots of exceptions. Otherwise the AI has to apply the rules itself, which can easily lead to incorrect answers. If there are so many cases that they cannot be described separately, state the exceptions and conditions explicitly (“if…, then…”).

5. Up-to-date information and metadata

  • Mark the owner, date of last update and period of validity at the beginning of the document. The AI can then tell what the information is based on.
  • Delete or archive outdated versions. Conflicting documents lead to conflicting answers.

6. A format AI can read

  • Write important information primarily as text. If you use a table, keep it simple: one header row, no merged cells. Also write out the key content of images and charts as text.
  • Favour web pages, SharePoint pages or markdown documents. Word and PDF files require special processing before AI can make use of them, so they are weaker sources. AI cannot read scanned images or handwritten attachments.

Check before publishing

  • Does the document have a clear topic and a descriptive name?
  • Are heading styles in use?
  • Can an individual section be understood without other documents or the rest of the text?
  • Are figures, names and deadlines visible?
  • Are the owner and date of last update marked?
  • Has the old version been deleted?