Guidelines for Structuring code snippets in technical writing for GenAI-based agents

Code snippets are essential for developers to quickly understand and integrate functionality into their projects. The code snippets help appeal to developers in terms of incorporating that code into their code base to achieve desired results.

Instead of adding code snippets as text, technical writers can use special HTML notations to describe this programming language code in such a way that web browser renders them properly in their knowledge base site/documentation site.

This blog gives you high-level information about how to structure your code snippets for GenAI-based agents that sit on top of your knowledge base content.

Code snippets characteristics

The code snippets possess distinct characteristics that need to be accounted for that enable them to be picked up by GenAI-based agents. These are the important metadata that need to be added to the code snippet.

Programming language

The programming language of the code snippet should be specified inside the tag using the identifier data language.
For example, the values for data-language includes Powershell, Java, Python, and other supported languages.

Description

The code segments are incorporated within header tags ranging from H1 to H6. The title or other metadata that is added as part of the headings where the code block is present would provide a high-level description of the purpose of the code block.