技术文档提示
使用准确的技术表达编写 README 文件、API 文档和操作指南
技术文档提示 是 CoddyKit 上的免费 AI Prompt Engineering 课时。 这是第 3 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 AI Prompt Engineering 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Prompt Engineering 课程共包含 4 节课。
技术文档是一种体裁
技术文档是一种具有特定规范的独立写作体裁：重精确而非文风，重结构而非叙事，重完整而非简洁。适用于博客文章或电子邮件的提示词，会为技术文档生成错误的语体。
有效的技术文档提示词会明确体现这种体裁——文档类型、读者的预期知识水平、该文档类型的标准结构，以及表达方式规范（操作指南通常使用第二人称，参考文档通常使用第三人称）。
README 文件提示词
README 是项目的入口。它的标准结构已经相当成熟。有效的 README 提示词会明确指定每个部分：
- 项目名称和单行描述
- 功能说明：用 2-3 句话说明用途
- 前置条件：需要安装哪些内容
- 安装：包含命令的编号步骤
- 快速开始：最小可运行示例
- 配置：环境变量和选项
- 参与贡献：如何提交拉取请求
- 许可证
在提示词中提供所有部分的名称，可以生成完整的 README。如果没有明确指示，缺少的部分就会被省略。
代码中的 README 提示词
一个接受项目元数据的结构化 README 生成器：
import openai
client = openai.OpenAI(api_key='sk-...')
def generate_readme(project_name, description, language, dependencies,
install_steps, quick_start_example, config_vars, license_type):
prompt = f'''Write a README.md for the following project.
Project name: {project_name}
Description: {description}
Language/stack: {language}
Dependencies: {dependencies}
Installation steps: {install_steps}
Quick start example: {quick_start_example}
Key configuration variables: {config_vars}
License: {license_type}
Structure the README with these sections in order:
1. Project title and badge line (GitHub stars, license)
2. One-sentence description
3. Features (3-5 bullet points)
4. Prerequisites
5. Installation (numbered steps with code blocks)
6. Quick Start (minimal working example in a code block)
7. Configuration (table: Variable | Description | Default)
8. Contributing (2-3 sentences)
9. License
Voice: second person imperative for steps ("Run...", "Install...").
Code blocks: use correct language identifiers.
Do not add placeholder content — only include sections where I provided information.'''
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': prompt}]
)
return response.choices[0].message.content应用程序接口文档提示词
应用程序接口文档具有严格的结构。每个端点条目都需要包括：HTTP 方法、路径、描述、参数、请求正文、响应格式、错误代码和示例。提示词必须明确指定所有这些内容：
“为一个 REST 端点撰写应用程序接口文档。请包括：方法（POST）、路径（/api/v1/users）、描述、参数表（名称、类型、是否必需、描述）、请求正文 JSON 示例、成功响应（200）JSON 示例，以及带有 JSON 示例的错误响应（400、401、422）。表达方式：第三人称、现在时。使用 Markdown 表格呈现参数。”
每个结构要素都必须明确列出——模型不会猜测您的文档规范。
操作指南提示词
操作指南具有流程性：通过编号步骤，将读者从状态 A（问题）引导至状态 B（解决方案）。操作指南的提示词元素包括：
- 前置条件：开始前必须满足的条件
- 结果：读者将完成的内容
- 步骤：按编号列出，每步只执行一个操作，不要在一个步骤中包含多个操作
- 代码示例：在适用时，每个步骤提供一个，并注明所用语言
- 验证：读者如何确认每个步骤已成功完成
- 故障排除：针对两三个最棘手步骤，说明常见的失败情况
文档提示词中的技术准确性
与大多数内容类型相比，技术文档对准确性的要求更高。以下是提高文档提示词准确性的两种方法：
提供实际代码：粘贴真实的函数签名、配置选项或应用程序编程接口规范。这样，模型记录的是实际存在的内容，而不是编造细节。
要求加入验证步骤：“写完每个步骤后，请注明您对用户环境或系统行为所作的任何假设。请标出我在发布前应当验证的内容。”
切勿在未经技术审查的情况下使用人工智能生成的文档——模型会自信地记录并不存在或不正确的内容。
文档中的代码示例质量
代码示例是技术文档中最重要的元素。请在提示词中明确提出要求：
- “每个主要概念都包含一个可运行的代码示例。示例应当自包含，让读者可以复制、粘贴并运行。”
- “同时展示正确用法和一种常见错误，并通过注释解释该错误为何会导致失败。”
- “代码示例应使用真实的变量名和数据，而不是‘甲’‘乙’‘测试’。”
- “语言：Python 3.11。使用类型提示。为网络调用加入错误处理。”
如果没有明确的代码示例要求，模型可能生成不完整的伪代码片段，实际上无法运行。
文档语气与风格
技术文档有其特定的语气，这种语气不同于其他写作类型：
- 操作步骤使用第二人称祈使语气：“点击设置。选择应用程序编程接口选项卡。输入您的密钥。”
- 参考文档使用第三人称：“authenticate() 方法返回一个有效期为 24 小时的承载令牌。”
- 使用现在时：“函数返回……”，而不是“函数将返回……”
- 不要使用模棱两可的表达：使用“运行此命令”，而不是“您可能需要考虑运行此命令”
- 术语保持一致：全文对同一概念使用相同术语，不使用同义词
变更日志与发行说明提示词
变更日志和发行说明有一种提示词应当明确规定的惯用格式：
“请为 2.3.0 版本撰写发行说明。格式：版本标题、发行日期，然后分为三个部分：‘新增’（新功能）、‘变更’（对现有功能的修改）、‘修复’（错误修复）。每项占一行，使用主动语态，并以动词开头。受众：集成此库的开发人员。语气：准确、中立，不使用营销语言。以下是变更内容：[列出实际变更]。”
将实际变更作为输入数据可以确保准确性。如果不提供这些内容，模型会编造听起来合理但实际上虚构的发行说明。
文档完整性检查
生成技术文档后，请运行完整性检查提示词：
import openai
client = openai.OpenAI(api_key='sk-...')
def check_documentation_completeness(doc_text, doc_type='how-to guide'):
checklist = {
'how-to guide': [
'Prerequisites stated?',
'Expected outcome stated?',
'Each step is a single action?',
'Code examples included where relevant?',
'Validation step for each major action?',
'Common errors addressed?'
],
'readme': [
'One-line description present?',
'Installation steps numbered with commands?',
'Quick start example included?',
'Configuration variables documented?',
'License specified?'
]
}
items = checklist.get(doc_type, [])
check_prompt = f'Review this {doc_type} and answer each question (Yes/No + brief note):\n'
for item in items:
check_prompt += f'- {item}\n'
check_prompt += f'\nDocument:\n{doc_text[:2000]}'
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': check_prompt}]
)
return response.choices[0].message.content为不同技术背景的受众翻译术语
技术文档通常需要同时服务于技术和非技术读者。一种实用的提示词模式是：
“请将这份文档分为两个层次。第一层：用 3 句话提供非技术摘要（说明它的功能、重要性以及使用时机）。第二层：提供完整的技术规范。在两个层次之间使用清晰的视觉分隔线。这样，非技术管理人员可以阅读摘要后停止；技术读者则可以跳过摘要，直接阅读规范。”
双层文档比试图编写一个无法充分服务于两类受众的版本更有用。
知识检查：技术文档提示词
您正在编写提示词，为 50 个端点生成应用程序编程接口文档。最重要的质量要求是，文档准确反映应用程序编程接口实际执行的操作，而不是模型想象的内容。哪种方法最能确保准确性？
回顾：技术文档提示词
技术文档是一种独特的文体，要求内容精准、结构清晰，并在操作步骤中使用第二人称祈使语气。有效的提示词会明确文档类型，按名称指定必需的部分，并规定代码示例的要求（自包含、使用真实的变量名以及指定语言版本），同时明确文档的语气规范。
确保准确性的最关键方法是：始终将实际代码、应用程序编程接口规范或配置数据作为输入提供给模型，绝不要要求模型编造技术细节。在发布人工智能生成的文档前，始终加入人工技术审查。
在最后一课中，您将把提示技巧应用于创意和故事类内容。
常见问题解答
「技术文档提示」课时是免费的吗？
是的 — 「技术文档提示」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Prompt Engineering 课程的其余内容，请升级到 CoddyKit PRO。 AI Prompt Engineering 课程共包含 4 节课。
「技术文档提示」这节课中我会学到什么？
使用准确的技术表达编写 README 文件、API 文档和操作指南 你通过在浏览器中直接运行的动手代码来练习 AI Prompt Engineering，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 AI Prompt Engineering 需要有经验吗？
无需任何先前经验。CoddyKit 上的 AI Prompt Engineering 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 4 节。
「技术文档提示」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 AI Prompt Engineering 课中编写并运行代码吗？
能。每节 AI Prompt Engineering 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。