技术写作中代码片段的结构化：面向AI助手的优化

许多软件文档都包含代码片段，以帮助开发人员快速入门。代码片段在帮助开发人员理解流程功能以及与软件交互的能力方面起着至关重要的作用。这些代码片段可能简单到只是一段CSS/JS代码，也可能包含一些软件代码片段，比如一个用于与您的软件产品交互而需要执行的函数。代码片段有助于吸引开发人员将其整合到自己的代码库中，以实现预期的结果。

技术作者无需将代码片段添加为纯文本，而是可以使用特殊的HTML标记来描述这些编程语言代码，以便网络浏览器在其知识库网站/文档站点中正确渲染它们。本文为您提供关于如何为构建在您知识库内容之上的基于GenAI的智能体结构化代码片段的高层次信息。

代码片段具有需要被考虑在内的特殊特性，以便能被基于GenAI的智能体识别。代码片段被包裹在和HTML标签内。以下是需要添加到代码片段中的重要元数据。

应在标签内部使用标识符data-language指定代码片段的编程语言。

例如，data-language的值可以是Powershell、Java、Python等。 代码位于 HTML 元素内 

代码被包含在 H1 至 H6 等标题标签内。当存在代码块时，作为标题一部分添加的标题或其他元数据将提供关于该代码块用途的高级描述。

添加的代码可以根据编程语言的语法包含开发者注释。

代码注释位于代码块内部

在使用Markdown格式进行内容创作时，使用三个反引号 "`" 在代码片段前后进行包裹。要为代码应用特定语言的语法高亮，请在开头的三个反引号后注明编程语言。

例如：

Ruby
[在此添加您的代码片段]

以下是在重构代码时应遵循的一些最佳实践：

一旦实施了这些最佳实践，基于 GenAI 的智能体就可以摄入代码片段，并在用户询问时将其提供给他们。如果用户向聊天机器人询问在特定编程语言中实现某些功能的代码片段，那么聊天机器人可以根据知识库内容生成一个代码片段。

代码片段是软件文档不可或缺的一部分，它通过展示可用的代码，使开发人员能够立即获得价值。这些代码片段可以成倍提高开发人员的工作效率。如果按照最佳实践创建代码片段，那么为基于 GenAI 的智能体对此内容进行预处理就会变得很容易，且不会丢失任何信息。一旦被要求生成回复，该聊天机器人就可以用正确的编程语言生成正确的代码片段，从而提高开发人员的工作效率。

直观的知识库软件，可轻松添加您的内容并将其与任何应用程序集成。试试 Baklib 吧！

将所有文档集中管理，并使每个人都能轻松搜索。

Baklib 是一个内容管理系统，可帮助具有复杂内容需求的全球企业随时随地创建、管理和交付内容。Baklib 平台最适合跨行业的组织，这些组织管理多个品牌、网站、工作流和多种语言的内容类型，并且需要一个安全且可扩展的平台供开发团队使用，同时也为内容和营销团队提供直观的编辑工具来管理其关键任务内容。全球 800 多家知名品牌已选择 Baklib 作为其主要平台，以扩展其内容运营并增强其营销团队的能力，从而减少对开发人员的依赖，使团队能够更快地进入市场，而不会牺牲其 CMS 的灵活性和安全性。