Start Free Trial Book a Demo
Webinar on Documentation Insights: Role of Context in Technical Communication - Jan 22, 2025 | 02:30PM UTC - Register Now!
View all
Structuring code snippets in technical writing for GenAI-based agents

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

Category: AI

Last updated on Aug 27, 2024

Many of the software documentation contains code snippets to help developers get started quickly. Code snippets play a vital role in helping developers understand the functionality of the process and the ability to interact with software. The code snippets could be as simple as a CSS / JS code. The code snippets may also contain pieces of software code that may be a function to be executed to interact with your software product. 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 have special characteristics that need to be accounted for that enable them to be picked up by GenAI-based agents. The code snippets are enclosed within <code> and </code> HTML tags. 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 </code> tag using the identifier data language.

For example, the values for data-language are Powershell, Java, Python, and so on.

Code snippet

Code is given inside <code> HTML element

Description

The code is included are part of header tags such as H1 – 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

Code comments

The added code can include developer comments based on the programming language syntax.

Javascript Block

Code comments are given inside the code block

Adding code snippets

While using markdown format for content creation, use triple backticks “` before and after to include code snippets. To apply a language’s specific syntax highlighting, include the programming language after the first 3 backticks.

For example:

“`Ruby

[add your code snippet]

“`

Also Read: Guidelines for Structuring tables in technical writing for GenAI agents

Best practices

The following are some of the best practices to be followed while refactoring the code:

  • Code should be given inside the code blocks.
  • Code should be written in the code that applies to a chosen language.
  • Ensure the code snippets are quality-checked so that they work when used!
  • Add comments inside the code snippets using the chosen programming language syntaxes.
  • The code snippets can be written using the markdown language or the knowledge base tool you are using might have a provision to add these code blocks using any pre-defined template. It is important to note that all the code snippets are rendered in the HTML format using the <code> tag in the browser

Once these best practices are implemented, GenAI-based agents can ingest code snippets and make them available for users if asked. If the user asks the chatbot for code snippets to achieve certain functionality in the specific programming language, then the chatbot can generate a code snippet based on the knowledge base content.

Conclusion

The code snippets are indispensable to software documentation that empowers developers to get value immediately by showing usable code. These code snippets enhance the productivity of developers by multifold. If code snippets are created as per the best practices, the preprocessing of this content for GenAI-based agents becomes easy without any loss of information. Once asked to generate a response, this chatbot can generate the right code snippets in the right programming language to increase the developer’s productivity.

An intuitive knowledge base software to easily add your content and integrate it with any application. Give Document360 a try!

GET STARTED
Document360

Related Articles