Make Your Docs Ready for AI

Several years ago, we wrote documents for humans. Now we write documents for AI 😀.

And, to be honest, machines require much more structured text than humans do. Poorly structured content leads to incorrect chunking and low quality answers during RAG context evaluation.

Common recommendations for modern docs:
🔸 Use structured format: md, html, asciidoc.
🔸 Provide metadata: important dates, tags, context and document goal.
🔸 Define glossary: describe key terms and abbreviations.
🔸 Organize content hierarchy: create clear structure using descriptive headings and subheadings.
🔸 Use lists: prefer bulleted or numbered lists instead of comma-separated enumerations.
🔸 Include text description for visual information: duplicate important details from diagrams, charts, and screenshots via text.
🔸 Use simple layout: do not use complex visuals and tables, prefer simple headings, lists and paragraphs.
🔸 Keep related information together: design content in a way that each section contains sufficient context to be understood independently.
🔸 Describe external references: when referencing external concepts, provide brief context and explanation.

As you can see, the recommendations are quite simple. And moreover, it feels like I became a machine a long time ago: I hate long paragraphs without clear structure and prefer well-structured documents for years.

#ai #documentation