Chris Chinchilla: Writing for Robots

This talk was presented at the AI The Docs online conference on April 4, 2024. We are thrilled to share the recording and the summary with you.

Visit the talk summary page to see all of the presentations from the conference.

Chris Chinchilla

Independent Technical Communicator

Chris' presentation

In his presentation, Chris discusses the evolving landscape of documentation, emphasizing the need for creating high-quality content that serves both human readers and machine readers, such as bots and large language models (LLMs).

Key Takeaways

Machine Readers as Primary Consumers

• Publicly available documentation is frequently read by bots and LLMs.
• Writing content that is good for human readers also makes it suitable for machine readers.

Benefits of SEO and Machine Readability

• Search engine optimization (SEO) aids in making documentation accessible to users and machine readers.
• Techniques that help SEO also enhance the readability of documentation by LLMs.
   

Best Practices for Writing Documentation

• Headings and Structure
  • Use active and descriptive headings to reflect common user queries.
  • Maintain a clear hierarchy with one top-level heading followed by appropriately nested subheadings.
• Meaningful Links
  • Avoid vague link texts like "click here" or "read more"; instead, use descriptive texts that convey the link's purpose.
  • Ensure links are functional and avoid formats that LLMs cannot process.
• ALT Tags for Images
  • Use descriptive ALT tags for images to enhance accessibility and provide context for machine readers.
• Context and Descriptions
  • Provide context for all elements, including tables, code snippets, and videos, to help machine readers understand their relevance.

The Role of Technical Writers

• High-quality content is essential for training LLMs, ensuring accurate and helpful responses.
• Technical writers, with their expertise in clear and structured writing, are crucial in this process.

Chris concludes by stressing that good documentation practices, which have always been beneficial, are now even more critical in the age of advanced machine readers.