在人工智能时代如何提升自己的能力：从技术文档编写者成长为开发人员培训师

直到最近，构建一份技术写作作品集其实很简单：只需创建一个网站，添加一些文章列表，描述自己的写作经验，并链接到自己的社交媒体账号即可。

但如今，这样的做法已经不够了。

开发人员现在可以让人工智能助手在几秒钟内生成API的使用说明、总结相关文档、编写教程大纲，甚至完成一篇编程文章的初稿。

这种情况改变了技术写作工作者应该具备的能力和技能。

如今，最重要的能力不再是仅仅写出技术上正确的句子，而是要深入了解相关技术，知道该写什么内容，验证这些说明是否有效，找出开发人员可能会遇到的问题，并将这些知识转化为可供他人实际使用的文档。

这就是我创建这份作品集网站的初衷。

我构建这个网站的目的并不仅仅是为了展示一份在线简历，而是想让大家了解我是如何开展开发者教育工作的。

这篇文章会介绍我是如何制作这份作品集的，其中使用了哪些技术，是如何组织这些内容的，又是如何将其部署到线上的，以及在这个人工智能盛行的时代，这个项目让我学到了什么关于如何成为一名合格的技术写作工作者的知识。

目录

• 技术写作发生了哪些变化？

• 为什么人工智能并没有让技术写作工作者变得多余？

• 你应该能够将自己所教授的内容转化为实际作品。

• 我的作品集本身就是一个软件项目。

• 一份技术写作工作者的作品集应该包含哪些内容？

• 我的作品集所使用的技术

  • 为什么我选择了React技术？

  • 为什么选择TypeScript？

  • 为什么使用TanStack Start框架？

  • Vite如何帮助管理开发与构建流程。

  • Tailwind CSS如何负责样式设计。

  • Lucide React为何能提供图标资源。

• 如何理解package.json文件。

• 如何理解路由文件的作用。

• 组件如何帮助分离可复用的界面元素。

• 资源文件也是文档编写过程中不可或缺的一部分。

• 配置文件的重要性。

• 我在开发与文档编写过程中是如何运用人工智能的。

• 对于技术写作工作者来说，最重要的AI技能是什么？

• 我的开发工作流程。

• 如何将作品集部署到Netlify平台上。

• 为什么Git对技术写作工作者来说如此重要？

• 初学者应该学习哪些内容才能成为一名技术写作工作者。

• 你的作品集应该能够证明你具备这些技能。

• 如果我现在开始重新做这份作品集，我会选择构建什么内容。

• 如何通过实际项目来检验一份作品集的质量。

• 这份作品集让我学到了什么。

• 你不必是房间里最优秀的开发人员，也能做好这份工作。

• 最后的思考。

技术写作发生了哪些变化？

让我们先从一个更重要的问题开始：为什么技术写作者需要了解软件开发？

因为受众已经发生了变化。

当开发人员阅读API指南时，他们需要的不仅仅是能够解释某个接口功能的人，而是那些能够理解这个接口在应用程序中具体作用的人。

以一个简单的API指令为例：POST /api/users

一个初级的写作者可能会这样解释：

这个接口用于创建新用户。

从技术角度来看，这种表述可能是正确的。但开发人员很可能会接着提出以下问题：

• 这个接口需要哪些认证方式？

• 需要哪些请求头信息？

• 请求体应该包含哪些内容？

• 哪些字段是必填的？

• 如果验证失败会发生什么？

• 成功的响应应该是什么样的？

• 会返回什么样的状态码？

• 如果输入的电子邮件地址已经存在，会怎样处理？

• 这个接口是否具有幂等性？

• 在JavaScript或Python中应该如何处理这些响应数据？

优秀的开发文档应该能够回答这些问题。

而这不仅仅需要写作能力，还需要进行技术性的分析和研究。

正因如此，我认为技术写作者的角色正在从技术写作者向开发教育者转变。

开发教育者的职责不仅仅是解释技术知识，更重要的是帮助其他开发人员正确地使用这些技术。

为什么人工智能并没有让技术写作者变得多余

人工智能确实改变了我的写作方式，但我不认为这意味着技术写作者应该避免使用人工智能。

正确的做法应该是以不同的方式利用人工智能。

人工智能在处理重复性工作方面表现得非常出色：

• 生成初始的文档大纲

• 提供多种解释方案供选择

• 简化复杂的句子结构

• 找出可能存在的边界情况

• 将笔记整理成初稿

• 生成测试用例

• 解释不熟悉的语法内容

• 审核文档的结构合理性

• 帮助想出各种示例

• 比较不同的实现方法

但这里有一个重要的区别：人工智能可以加速我的思考过程，但它不能取代我对内容正确性的责任。

如果人工智能助手生成了一个Node.js的示例代码，我仍然需要亲自运行它并验证其准确性。

如果它解释了某个API的功能，我也需要将它的解释与实际的API实现或官方文档进行对比。

如果它建议执行某个命令，我同样需要亲自执行这个命令。

如果它生成了一个教程，我也应该像读者一样从头开始按照这个教程来学习。

这种工作流程使人工智能的角色从“帮我撰写这篇文章”转变为“帮助我进行研究、测试、分析问题，并对这篇文章进行改进”。

这种关系要实用得多。

你应该能够将自己所教授的内容付诸实践

对于那些想要成为专注于开发领域的技术文档编写者的人来说，这或许是最重要的建议。

在开始编写文档之前，你不一定非得成为一名高级软件工程师，但你必须能够理解代码并对其进行解释。

你应该充分了解开发流程，这样才能熟练地查看代码仓库、安装依赖项、运行应用程序、分析错误信息、修改代码、测试示例，并能清楚地说明各项操作的具体效果。

例如，如果你在编写React教程，那么你必须对React有足够的了解，才能判断某个示例是否完整。

如果你在为REST API编写文档，那你就必须掌握HTTP方法、请求头信息、认证机制、状态码、JSON数据格式以及错误处理方法。

如果你在介绍GitHub Actions，你就需要理解工作流程、作业任务、触发条件、执行工具、保密设置以及部署步骤等内容。

如果你在为Python包编写文档，那你必须能够安装该软件并运行其中的示例代码。

目标并不是要掌握所有知识，而是要具备足够的技术能力，以便对自己所编写的内容进行验证。

我在制作自己的作品集或任何技术文档时，都是按照这个标准来操作的。

我的作品集本身就是一个软件项目

我的个人主页一眼就能让人明白我的工作内容：

我编写的文档是开发人员真正可以用来实践的。

这句话是我特意写出来的。

我不想让潜在的客户花费两分钟的时间去判断我编写的内容是属于营销材料、博客文章还是技术文档。

这个网站从一开始就明确了我的定位：

软件工程师 × 技术文档编写者

随后，它还展示了我在四个主要领域的能力：

1. API与SDK文档编写

2. 量子技术及深度学习相关文档编写

3. 以代码为主的技术教程编写

4. 云技术、DevOps以及“文档即代码”相关工作

我的作品集还展示了我的实际工作流程：

1. 阅读代码仓库中的内容。

2. 根据这些代码编写示例程序。

3. 测试这些程序的功能。

4. 最终完成文档的编写并发布出来。

这样的工作流程比仅仅宣称“我是一名技术文档编写者”要重要得多。

一份作品集应该能够证明你的实际工作方式。

技术文档编写者的作品集应该包含哪些内容？

如果你现在才开始准备自己的作品集，不要先问“我的作品集网站应该是什么样的”；而应该先思考“潜在客户在信任我为他们编写文档之前，需要哪些证据？”

我会根据六项主要内容来构建我的作品集。

1. 明确的技术定位

不要让访客去猜测你的工作内容。

与其写成：作家 | 博主 | 内容创作者，

不如直接说明：技术作家 | API文档编写者 | 开发教育专家。

如果你也会编程，也可以写成：软件工程师 × 技术作家。

你的定位应该能让访客立刻明白你能为谁提供帮助，以及你能解决哪些类型的技术问题。

2. 实际案例

列出文章列表固然有用，但实际案例更为有效。

如果你声称自己负责编写API文档，那就展示一个具体的API示例；如果你说自己在编写SDK文档，那就提供一份SDK使用指南；如果你编写教程，就提供包含可复现代码的教程；如果你在编写DevOps相关文档，那就展示一份部署指南。

你的作品集应该能够证明：

这个人确实具备他们所声称的理解那些技术的能力吗？

3. 技术深度的体现

我的作品集涵盖了以下技术领域：

• JavaScript

• Python

• TypeScript

• React

• Node.js

• APIs

• Azure

• CI/CD

• Qiskit

• IBM Quantum

• Git

• Markdown

• Docs-as-code

你不需要列出30种技术——事实上，列出所有技术反而会削弱你的定位效果。只需选择那些你能真正展示自己能力的技术即可。

4>已发表的作品

已发表的文章能证明你有能力向读者清晰地解释技术概念。

我的作品集将我的工作成果与开源项目以及我的技术博客联系起来。

但不要只是简单地说：我发表了20篇文章。要真正展示这些文章，让读者能够查看你的工作成果。

5>项目案例

项目案例有助于弥合写作与实际开发之间的差距。

一个优秀的项目描述应该能回答四个问题：

• 面临的问题是什么？

• 你完成了什么工作或编写了哪些文档？

• 项目中使用了哪些技术？

• 这个项目最终实现了什么目标？

一个项目不应该仅仅是一个使用React技术的作品集网站——这样的描述几乎无法让读者了解你的实际能力。

而应该像这样描述：

使用React、TypeScript、TanStack Start、Tailwind CSS以及Netlify部署工具，制作了一个面向开发者的技术写作作品集。

这样的描述才能真正体现你的技术实力。

6>明确的下一步行动建议

你的作品集应该能让访客清楚地知道接下来该做什么。

以一个具体的提议来结束对话，例如：请将你的API仓库链接或SDK文档发送给我，我会指出其中存在的具体文档缺失问题。

这比仅仅说“请联系我进行技术写作工作”要有效得多。

第一种表达方式为潜在的客户提供了具体的行动方向。

我的作品集所依赖的技术栈

我目前使用的作品集是建立在现代的React技术栈之上的。

其中主要包括以下技术：

• React

• TypeScript

• TanStack Start

• TanStack Router

• Vite

• Tailwind CSS

• shadcn/ui组件

• Lucide React

• npm

• Git与GitHub

• Netlify

关键并不在于你必须使用相同的技术栈——实际上，你完全可以用纯HTML和CSS来构建技术写作作品集。

我选择这种现代技术栈，既有实际原因，也有一定意图。

我想向人们展示自己是一个与开发人员合作的人，而我的作品集本身就应该能够证明我能够适应现代的开发流程。

为什么使用React?

React提供了一种基于组件的方式来构建用户界面。

与其将整个网站放在一个庞大的HTML文件中，不如将其拆分成可重复使用的组件。

例如，导航组件可以在多个页面上被重复使用；按钮也可以在整个应用程序中被反复利用。项目卡片同样可以作为可复用的组件来设计，而无需重复编写代码。

从文档编写的角度来看，这种方式也非常有用。当你理解了基于组件的开发模式后，你就会开始从“可复用性”、“依赖关系”、“输入数据”、“输出结果”以及“行为逻辑”这些角度来思考文档的编写方式。

而这些恰恰是开发人员最关心的内容。

为什么选择TypeScript?

TypeScript为JavaScript添加了静态类型检测功能。

对于一个作品集项目来说，有人可能会认为使用TypeScript并不是必需的。

这个观点也有道理。

但事实上，使用TypeScript能够反映我在编写现代应用程序文档时所期望遇到的开发环境。

它还迫使我去思考数据在各个组件和函数之间流动的方式。

例如：

type Project = {
  title: string;
  description: string;
  technologies: string[];
  url: string;
};

这样一来，我就能够明确地知道一个项目应该包含哪些内容。

这种思维方式直接体现在技术文档的编写中。

在为API编写文档时，你实际上是在描述各种“契约”条款：

• 输入数据

• 输出结果

• 数据类型

• 必填字段

• 可选字段

• 可能出现的错误

• 预期的行为

为什么选择TanStack Start?

我的作品集在应用程序的结构设计和路由配置方面使用了TanStack Start。对于初学者来说，重要的并不是必须学习TanStack Start框架——其实你并没有这个必要。 真正重要的是，技术文档编写者应该能够熟练地使用各种开发框架。 当我在客户的代码仓库中遇到不熟悉的框架时，我需要能够回答以下这些问题：

• 路由文件放在哪里？

• 组件文件在哪里？

• 应用程序的配置信息在哪里？

• 共享的工具函数放在哪里？

• 资源文件（如图片、CSS文件等）在哪里？

• 数据在应用程序内部是如何流动的？

• 应用程序是如何构建起来的？

• 它是如何被部署到生产环境的？

这些问题比死记硬背某个具体的框架要重要得多。

Vite负责处理开发与构建流程

Vite既负责开发环境下的运行体验，也负责生成可用于生产环境的最终版本。 在开发阶段，我可以在本地运行应用程序，并在编辑代码的同时快速获得反馈。 而生产版本的构建过程会生成可供部署的资源文件。
对于这个项目来说，开发流程基本上就是：在开发时执行`npm install`和`npm run dev`命令，在准备发布到生产环境时执行`npm run build`命令。 Vite目前的文档将开发服务器和生产环境的构建过程描述为其工作流程中的两个核心环节。
对于技术文档编写者来说，重要的经验是：**必须明白开发环境和生产环境之间的区别**。 一个在`localhost`环境下运行的教程，并不意味着它也可以用于部署环境。
开发者需要了解：当应用程序从个人电脑迁移到生产环境后，哪些设置会发生变化。

Tailwind CSS负责处理样式设计

我使用Tailwind CSS来构建整个应用程序的视觉样式系统。 与其为每个组件单独编写复杂的自定义样式表，不如直接在代码中编写相关的辅助类。
例如：

<h1 className="text-4xl font-semibold leading-tight md:text-6xl">
  开发人员完全可以按照这些样式进行实际开发。
</h1>

这种方式让我们在调整间距、字体样式、响应式布局以及组件样式时能够更加高效地进行迭代。
对于技术文档编写者来说，重要的并不是“必须学习Tailwind CSS”，而是“要掌握足够的前端开发知识，从而理解你所负责描述的系统实际上是如何构建起来的”。

Lucide React提供图标资源

我使用Lucide React来为应用程序生成图标。
例如：

import { ArrowRight } from "lucide-react";

这样，组件就可以在需要的地方显示这些图标了。
像这样的小型依赖库虽然体积不大，但它们在现代前端项目的代码仓库中非常常见，因此了解它们的用途是非常有必要的。

在记录现有的代码库时，你需要弄清楚某个导入项是应用程序的一部分、第三方依赖库、框架的功能，还是本地工具。

当需要解释安装和配置步骤时，这种区分就显得非常重要了。

了解 package.json

在检查JavaScript项目时，我首先会查看的文件就是package.json。

这个文件能让我了解到很多关于该项目的信息。

它可能包含以下内容：

• 项目元数据

• 脚本配置

• 依赖关系

• 开发用依赖库

• 包配置信息

对于技术文档编写者来说，这个文件是JavaScript代码仓库中最重要的文件之一。

如果某个教程要求读者手动安装五个包，而这些包其实已经在package.json中列出了，那么这个教程就是在让读者做无用功。

读者实际上只需要执行npm install命令就可以了。

了解package.json文件的内容，可以帮助你避免编写与项目实际情况不符的说明文档。

理解路由文件

该应用程序使用路由文件来表示不同的页面。

例如，应用程序包含以下路由：

 /about
 /services
 /projects
 /writing
 /contact

每个路由负责渲染相应的页面。

比如，“contact”路由既包含了页面的元数据，也包含了用于渲染该页面的组件。

简化后的代码示例如下：

export const Route = createFileRoute("/contact")({
  head: () => ({
    meta: [
      {
        title: "联系Casmir Onyekani",
      },
    ],
  }),
  component: ContactPage,
});

这里关键不在于记住createFileRoute这个函数，而是要理解这段代码的具体作用。

路由文件定义了以下内容：

1. URL地址

2. 页面元数据

3. 用于渲染该页面的组件

正因为如此，源代码本身也就成为了一份非常有用的文档。

组件：分离可复用的界面元素

该项目还使用了可复用的组件。

与其从头开始编写每一个按钮、卡片、导航元素或用户界面组件，不如使用可复用的组件来封装常见的功能和样式。

在记录代码库时，这是我首先会关注的内容之一。

如果有人问“如何创建一个按钮”，如果项目中已经存在可复用的Button组件，我就不会让他们去复制40行代码，而是会引导他们使用项目里已有的抽象设计。

优秀的文档应该遵循软件的架构结构，而不是与其相冲突。

资源也是文档编写中不可或缺的一部分

这个项目组合中包含了诸如我的个人资料图片以及其他视觉资源。

这些资源通常存储在以下路径中：

public/
src/assets/

理解这些区别非常重要。

有些资源会被导入到应用程序代码中，而另一些则可以直接作为静态文件被使用。

在编写文档时，了解这种区别能够避免出现令人困惑的指令——比如要求开发人员导入一张实际上应该从公共目录中提供的图片。

再次强调，文档的质量往往取决于对那些看似微小的实现细节的理解程度。

配置文件的重要性

初入行的技术文档编写者可能会只关注源代码目录：

src/

但实际上，许多重要信息都存储在源代码目录之外的文件中。

像以下这些文件就会对整个项目产生重要影响：

package.json
vite.config.ts
tsconfig.json
.gitignore

根据项目的不同，还可能会遇到与eslint、prettier、Tailwind CSS或Netlify相关的文件。

这些文件能够说明项目是如何构建、测试、格式化以及部署的。

如果忽视了它们，就可能会错过开发工作中的一些关键环节。

我在开发和编写文档时如何使用人工智能

在制作这个项目组合的过程中，人工智能确实发挥了很大的作用。

但我并没有把它当作一个真正的开发人员来使用，而是把它视作一名辅助工具。这两者之间有着本质的区别。

假设我遇到了某个错误，我不会要求人工智能修复我的整个项目，而是会问它：请解释这个错误的原因，并指出导致这个错误的文件是什么。 然后我会仔细检查那个文件，可能会进一步询问：造成这个错误的三种可能原因分别是什么？之后我就会针对这些可能性进行测试。 有时我也会要求人工智能检查这个组件是否存在可访问性方面的问题，然后我自己再去验证这些建议是否正确。 这样就能形成一个反馈循环：

        人工智能的建议
             ↓
        我对问题的调查
             ↓
        对代码的修改
             ↓
        运行应用程序
             ↓
        测试结果
             ↓
        记录哪些方法是有效的

我认为技术文档编写者就应该这样使用人工智能。 利用人工智能来提高工作效率，但千万不要将其作为替代自己技术判断的工具。

对技术文档编写者来说，最重要的是哪种人工智能技能

基于提示进行写作确实很有帮助，但我认为还有比这更重要的能力：验证能力。一个精美的提示并不能保证能得到正确的答案。 如果人工智能助手给你给出了这样的指令：npm install some-package，你就需要确认这个包是否存在。 如果它提供了API示例，你就需要实际测试这些请求。 如果它给了React开发示例，你就需要运行这个应用程序。 如果它声称某个框架支持某种功能，你就需要根据该框架的当前文档或源代码来验证这一说法是否正确。 这一点尤其重要，因为软件会不断更新。两年前还正确的教程，如今可能已经包含了过时的指令。 因此，技术写作人员应该养成这样的习惯：先检查源代码 → 实现过程 → 测试结果 → 最终解释，而不是直接从提示 → 答案 → 发布开始工作。

我的开发工作流程

在进行技术项目开发时，我会按照以下顺序进行操作：

        理解项目需求
            ↓
          编写代码
            ↓
          进行测试
            ↓
        编写文档
            ↓
         审核内容
            ↓
        最终发布

这种工作流程同样适用于技术写作。 假设客户提供了一个API仓库，我不会立刻开始编写文档。 首先，我会：

• 仔细研究这个仓库

• 了解该应用程序的具体工作机制

• 安装所有所需的依赖项

• 运行整个项目以验证其功能

• 查找相关的API接口

• 实际发送请求并观察响应结果

• 记录下所有实验过程中的细节

只有完成这些步骤后，我才会开始编写正式的文档。 虽然这种做法比让人工智能生成一篇2000字的文章要耗时得多，但这样生成的文档确实更有可能具有实际价值。

将作品集部署到Netlify上

当我的应用程序在本地环境中能够正常运行后，接下来就需要将其发布到网上。 我使用了Netlify这个平台。对于基于Git的项目来说，它的部署流程非常简单明了。 基本的操作步骤如下：

        本地项目
             ↓
            Git仓库
             ↓
        GitHub托管平台
             ↓
           Netlify服务器
             ↓
        生产环境网站

Netlify能够自动连接Git仓库，并在代码发生变化时立即构建并部署项目。 对于使用Vite框架的项目来说，常见的生产环境配置包括：

• 构建命令：npm run build

• 发布目录：dist/client

这意味着Netlify会执行构建命令，并将生成的生产环境文件上传到服务器上。 对于技术写作人员来说，这个概念非常重要。部署文档不应该只是简单地说“将你的应用程序部署到Netlify上”，而应该详细解释仓库、构建命令、输出目录以及托管平台之间的关系。

为什么Git对技术写作人员来说如此重要

Git不仅仅是一种开发工具，它也是一种文档编写工具。

如果文档与源代码保存在同一个版本库中，那么Git能为你提供以下功能：

• 版本历史记录

• 分支管理功能

• 拉取请求机制

• 代码审核流程

• 变更跟踪功能

• 协作工具

想象一下，如果有开发人员修改了某个API接口的地址，那么由于文档也保存在同一个版本库中，这一更改就能通过相同的工作流程触发文档的更新。这就是“将文档视为代码”这一理念的基础。

你不需要在一开始就成为Git专家，但至少应该掌握以下基本操作：

git clone
git checkout
git pull
git add
git commit
git push

你还应该了解拉取请求的原理，以及如何将本地分支中的更改推送到共享版本库中。

初学者若想成为技术写作人员，应该学习哪些内容

如果你现在刚开始从事技术写作工作，我认为你的学习内容可以分为五个方面。

1. 编程基础

首先选择一种编程语言进行学习。

JavaScript或Python都是不错的选择，因为这两种语言在许多开发环境中都被广泛使用。

你需要学习的内容包括：

• 变量

• 函数

• 对象

• 数组

• 条件判断语句

• 循环结构

• 模块化编程

• 错误处理机制

• 异步编程技术

• 包管理工具

你不需要掌握所有编程语言，但需要具备足够的编程知识，以便理解开发人员的工作流程。

2. Web与API基础

如果你想编写技术文档，就必须了解Web的基本工作原理。

你需要掌握的内容包括：

• HTTP协议

• URL地址

• HTTP请求方法

• 状态码

• 请求头信息

JSON格式

• 认证机制

• REST API接口

• 请求体与响应体结构

• cookie技术

• token验证方式

之后，你可以尝试实际操作一下。例如，创建一个简单的API并为其编写文档。

通过这样的实践，你所能学到的关于API文档编写的知识，远远超过阅读几十篇技术写作相关的文章。

3. 开发工具使用

你需要熟悉以下开发工具：

• VS Code

• Git

• GitHub

• 终端编程环境

• 包管理工具

• 浏览器开发者工具

Markdown格式编写工具

• 环境变量配置方法

JSON数据格式

• 基本调试技巧

这些工具是开发者文档生成与使用所依赖的环境的重要组成部分。

4. 文档编写技能

学习如何撰写以下内容：

• README文件

• 入门指南

• 教程

• API参考文档

• SDK使用指南

• 故障排除指南

• 概念性文档

• 迁移指导手册

• 配置指南

并且要明白，这些不同的文档格式有着各自不同的用途。

API参考文档并非教程，教程也不是概念性指南，而README文件更不能替代一个完整的开发者门户。

优秀的技术文档编写者能够清楚区分这些差异。

5. 人工智能辅助的工作流程

最后，学习如何有效利用人工智能。

你可以用它来：

• 辅助研究工作

• 进行头脑风暴

• 审核代码

• 生成测试用例

• 协助编辑内容

帮助进行总结归纳

• 优化代码结构

• 识别知识漏洞

• 对比不同解释

但你需要对自己负责以下方面：

• 技术决策的制定

• 代码来源的核实

• 代码测试工作

• 确保内容的准确性

• 示例代码的编写

• 最终解释的确定

我们的目标不是与人工智能在生成文字方面竞争，而是要成为那些知道哪些内容是必要的、以及这些内容是否真实的人。

你的作品集应该能够证明你具备这些技能

正因如此，我认为技术文档编写者的作品集不应该被视作一份在线简历。

你的作品集实际上是一个展示自己能力的平台。

• 如果你声称自己了解API，那就用实际文档来证明这一点。

• 如果你认为自己熟悉软件开发，那就展示一些你参与过的软件项目。

• 如果你会编写教程，那就发布一些带有可复现示例的教程。

• 如果你了解Git和“文档即代码”的理念，那就展示通过开发流程保存和维护的文档。

• 如果你能有效地利用人工智能，那就展示一个由人工智能辅助但你仍然负责最终审核的工作流程。

你的作品集本身就能成为证明你能力的证据。

如果我今天开始重新开始，我会做些什么

如果你是初学者，不需要像我一样制作复杂的作品集。

从小处着手吧。

先创建一个简单的网站，内容包括：

首页  
关于我们  
项目  
写作  
联系我们

然后再添加三个有代表性的项目。

项目1：API文档编写

构建一个简单的REST API。

为其编写文档，内容包括：

• 认证机制

• 接口端点

• 参数设置

• 请求体格式

• 响应内容

• 错误处理方式

• 示例代码

项目2：开发者教程

使用React或Python创建某个作品，然后编写一份教程，帮助其他开发者从零开始完成项目并使其能够正常运行。

项目3：部署指南

将该项目进行部署，并记录整个部署过程。 其中应包括所需的命令、配置信息、环境变量、构建流程以及故障排除步骤。

这样，你的作品集就不只是简单地宣称“我会编写技术文档”，而是真正证明了这一能力。

真实的作品集测试

这里有一个简单的测试方法，你可以用它来评估自己的作品集。

将你的作品集链接提供给一个不认识你的人。 然后向他们提出以下五个问题：

• 这个人主要从事什么工作？

• 他们为哪些人提供帮助？

• 他们掌握哪些技术知识？

• 在哪里可以找到他们工作的成果？

• 如果我想聘请他们，应该怎么做？

如果他们不能迅速回答这些问题，那么你的作品集可能还需要进一步完善。 你不需要添加更多的动画效果，也不一定需要增加页面数量——你需要的是更清晰、更有说服力的展示内容。

我的作品集教会了我什么

制作自己的作品集让我深刻体会到了在软件开发和技术写作过程中的一些重要道理： 技术写作越来越注重实际应用效果。 人工智能可以生成各种解释，但开发者需要的其实是那些与代码本身紧密相关的说明。 这才是真正的标准。 一个优秀的技术作家应该能够打开代码仓库，并对其中的内容产生浓厚的兴趣：

• 这个功能是用来做什么的？

• 为什么会有这样的依赖关系？

• 这些数据是从哪里获取的？

• 当请求失败时会发生什么？

• 为什么要采用这种配置方式？

• 开发者需要安装哪些软件或工具？

• 如果使用其他版本会带来什么后果？

• 这个工作流程中有哪些环节没有得到记录？

这些问题才是真正值得思考的关键。 写作的作用就是将这些答案清晰地传达给他人。

你不必是房间里最优秀的开发者

还有另一个需要澄清的误解： 成为一名专注于开发者的技术作家，并不意味着你必须以软件工程师的身份与他们竞争。 你的工作职责是不同的。 你需要具备足够的技术深度，以便理解系统的工作原理、对其进行测试，并能够清晰地表达这些内容；同时，你也需要具备从学习者的角度思考问题的能力。 这种结合是非常有价值的。 你始终需要在两种视角之间进行切换：

这个软件是如何工作的？
            ↕ 
开发者应该如何学习使用它？

这才是开发者教育的核心所在。

结语

我创建自己的作品集，是因为我希望潜在的客户和雇主看到的不仅仅是我的简历，而是我真正的能力。

我想让他们了解我的思维方式。

这个网站本身就是一个软件项目；这些项目体现了工程设计的精髓，而这些文章则展示了技术沟通的能力，代码体现了实现过程，而部署环节则展现了整个开发工作流程。

至于文档资料，它们证明了我是否能够将那些复杂的技术内容转化为其他开发者可以使用的实际工具。

在我看来，这才是现代技术写作作品集应该具备的功能。

不要仅仅创建一个说明“你是一名技术作家”的网站，而要制作出一些能让这种说法变得无可置疑的作品。

• 学习编程。

• 完成实际项目。

• 尝试剖析各种技术问题。

• 阅读开源代码库。

• 测试各种示例程序。

• 编写技术文档。

• 利用人工智能来提升工作效率。

最后，要验证所有这些内容是否真实有效。

因为未来，技术写作领域的关键不在于谁能写出最多的文字，而在于谁能够帮助其他开发者从“不明白这个概念”转变为“能够将其付诸实践”。