md-platform

Writing so both readers get good answers

A document in md-platform is read by colleagues and by the AI clients they connect. The useful discovery is that these two readers want almost the same thing, and where they differ, the machine's requirement is the stricter one.

A document that is genuinely clear to a new colleague is usually a document an assistant answers well from. A document that a colleague can follow only because they already know the context is one an assistant will get confidently wrong.

One document, one idea

A retrieved document is a unit. When a client searches, it gets excerpts and then reads whole documents — so a document covering four loosely related topics gets retrieved for all four and answers none of them well, because three quarters of what the model reads is noise for the question it was asked.

Split by the question a reader would arrive with, not by the department that owns the answer.

The opposite failure is real too: twelve documents that each hold one paragraph force a model to find all twelve, and it will find eight. If two documents are always read together, they are one document.

Titles that state the subject

The title carries more weight than anything else in the document. It is what ranks highest in search, it is what a client sees in list_documents before it has read anything, and it is the one line that decides whether a document gets opened at all.

  • "Wie wir Sicherheiten bewerten" — states the subject.
  • "Grundsätze", "Übersicht", "Notizen aus dem Workshop" — allude to it. A model listing thirty documents cannot tell what any of these are for.

Write the title as the question the document answers, or as the thing it describes. Never as where it came from.

Say the context the reader does not have

The most common reason an assistant answers wrongly is not that the document was missing — it is that the document assumed something the reader knew.

  • Say what a thing is before you say what to do about it. A document opening with "Für Bestandskunden gilt die verkürzte Frist" cannot be used by anybody who does not already know there are two.
  • Spell out abbreviations once, on each document that uses them. Documents are retrieved individually; a glossary elsewhere in the workspace is not in the model's context when it reads this one.
  • Date things that expire. "Ab nächstem Quartal" is unanswerable a year later. An absolute date stays true or becomes visibly stale, and both are better than plausible.
  • Say what is out of scope. A short "this does not cover X" prevents a confident answer built from a document that never claimed to cover X.

Structure that survives being quoted

Use real headings, in order, describing what is under them. Both readers navigate by them: a person skims, a screen reader jumps between them, and a model uses them to work out which part of a long document answers the question.

Prefer a list to a paragraph containing a list. Prefer a table to a paragraph describing a table. Anything with a clear shape should have that shape in the Markdown, because that shape survives being excerpted and prose does not.

Keep a document's first paragraph a summary of the document. It is what an excerpt is most likely to show.

Folders that match how people ask

Folders are how a search gets scoped, both in the web app and over MCP. That makes them a retrieval tool rather than a filing cabinet, and it changes what a good folder is.

Organise by the question, not the org chart. bewertung/ is useful because somebody asks about Bewertung; abteilung-4/ is useful only to people who already know what Abteilung 4 does — which is exactly the set of people who did not need to search.

Keep the tree shallow. Deep hierarchies encode a taxonomy that the people searching do not share.

Write for the search you have

Search matches words with stemming in the workspace's language, and it is not semantic. It will not connect "Frist" to "Deadline", and it does not infer.

So use the words your colleagues would search for, including the ones you find inelegant, and use them in the title and in the first paragraph. A document that carefully avoids repeating its key term is a document that does not come back.

Where an assistant will still be wrong

Being honest about the limits is more useful than pretending there are none.

  • A vague document produces a confident answer. Nothing in the pipeline detects that a document was ambiguous — the model reads it, resolves the ambiguity by guessing, and reports the guess in the same tone as a fact. This is the single largest source of wrong answers, and the only fix is upstream, in the document.
  • Two documents that disagree will not be flagged. Whichever ranks higher wins, silently. If you supersede a document, edit or delete it rather than writing a newer one beside it.
  • A model cannot read your uploads. Search indexes an upload's name and type, not the contents of the PDF. If a fact only exists inside an attachment, it does not exist as far as an assistant is concerned — put it in a document.
  • A retrieved path can be stale. Moving a document between folders breaks its old address, and a client that cached one will not find it. Tell your client to search rather than remember; see when a document moves.
  • Nothing here is a permission boundary you can write around. A connected client sees exactly what its person sees. Marking a paragraph "internal" in a document changes nothing at all.

The shortest version

Write the document you would want to be handed on your first day, with the abbreviations spelled out and the date on it. Both of your readers want that one.

Writing so both readers get good answers — md-platform