技术写作作品集怎么做：从静态简历到可验证的软件项目

技术写作作品集在过去很长一段时间里，做法相当简单：建一个站点，列一串文章标题，写一段写作经历，再挂上几个社交账号链接。这套做法在今天已经不够用了。当开发者可以随手让 AI 助手生成一段 API 说明、一份文档摘要、一个大纲甚至一篇代码教程的初稿时，写作本身不再是稀缺能力。真正稀缺的是：理解技术到足以判断该写什么、亲手跑一遍确认步骤是否可行、找出开发者会在哪里卡住，并把这些判断转化为别人能照着落地的文档。这篇教程讲的就是如何把作品集本身做成一个软件项目，用工程实践来证明这种能力。如果你需要一个在线工具来辅助整理和呈现这类内容，可以参考 Writer。

准备工作

在动手之前，先明确一件事：这篇教程不是让你照抄某一套技术栈，而是让你理解一套可复用的搭建思路。技术栈可以换，思路不能省。

需要具备的基础

• 能读懂 JavaScript 或 TypeScript 代码，至少能看懂变量、函数、类型声明。
• 会用命令行执行安装、启动、构建这类基础命令。
• 了解 Git 的基本操作：克隆、提交、推送、分支。
• 有一个 GitHub 账号，用于托管代码。
• 有一个静态站点托管平台的账号，用于部署。

如果你还不具备这些基础，建议先补上，因为作品集的价值恰恰在于它证明你能独立完成这些动作。写文档的人如果连依赖都装不起来、报错都读不懂，就很难写出让开发者信任的内容。

本地环境

• Node.js 与 npm：用于安装依赖、启动开发服务器、执行构建。具体版本要求以所用框架的官方说明为准。
• 代码编辑器：任意一款支持 TypeScript 的编辑器即可。
• Git：用于版本管理。

技术栈的构成

下面这套组合是常见的一种选择，各部分的职责需要分清楚：

组成部分	职责
React	以组件方式构建界面，把页面拆成可复用的片段
TypeScript	为 JavaScript 增加静态类型，明确数据结构的契约
TanStack Start / TanStack Router	提供应用结构与路由
Vite	负责开发与构建工作流
Tailwind CSS	负责样式
shadcn/ui 组件	提供现成的界面组件
Lucide React	提供图标
npm	包管理
Git 与 GitHub	版本管理与代码托管
Netlify	部署与发布

需要强调的是，用纯 HTML 和 CSS 也能做出技术写作作品集。选择现代应用栈的理由有两层：一层是实用，另一层是刻意为之——你在向开发者展示自己，作品集本身就应该证明你能在现代开发工作流里干活。

操作步骤

第一步：先想清楚作品集要回答什么问题

不要一上来就问「我的作品集网站该长什么样」，而要先问：「潜在客户在把文档工作交给我之前，需要看到什么证据？」围绕这个问题，作品集应该覆盖六个方面。

清晰的技术身份。不要让访客猜你是做什么的。与其写「写作者 | 博主 | 内容创作者」，不如直接写「技术写作者 | API 文档 | 开发者教育者」，或者如果你也写代码，就写「软件工程师 × 技术写作者」。定位要一眼看出你帮谁解决什么技术问题。

可运行的示例。文章列表有用，但可运行的示例更有用。你说你写 API 文档，就展示一个 API 示例；你说你写 SDK 文档，就展示一份 SDK 指南；你写教程，就给出包含可复现代码的教程；你写 DevOps 文档，就展示一份部署指南。作品集要能回答：这个人真的能解释他声称掌握的技术吗？

技术深度的证据。可以覆盖 JavaScript、Python、TypeScript、React、Node.js、API、云平台、CI/CD、Git、Markdown、docs-as-code 等方向。但不必罗列三十项技术，列得越全，定位反而越模糊。只选你真正能演示的那些。

已发表的作品。已发表的文章能证明你可以把技术概念讲给真实读者听。但不要只写一句「我已发表 20 篇文章」，要把文章展示出来，给读者一个能亲自查看你工作的入口。

项目。项目是连接写作与工程的桥梁。一个好的项目条目要回答四个问题：问题是什么？你构建或记录了什么东西？涉及哪些技术？这个项目证明了什么？不要只写「React 作品集网站」，那几乎没传达任何信息。写成「用 React、TypeScript、TanStack Start、Tailwind CSS 构建的面向开发者的技术写作作品集，并配有部署工作流」，技术能力就出来了。

明确的下一步动作。不要让访客看完不知道干什么。结尾给一个具体的提议，比如「把你的 API 仓库或 SDK 文档链接发给我，我会指出一处具体的文档缺口」，这比「有技术写作需求请联系我」强得多，因为它给了对方一件可以立刻做的事。

第二步：初始化项目并安装依赖

创建项目目录并初始化，然后安装依赖。具体命令以所选框架的官方脚手架说明为准，下面给出的是通用形态：

npm create vite@latest my-portfolio -- --template react-ts
cd my-portfolio
npm install
npm install tailwindcss
npm install lucide-react
npm run dev

安装完成后，开发服务器会给出一个本地地址，在浏览器打开即可看到初始页面。这一步的意义不只是「跑起来了」，而是你亲手验证了依赖安装、脚本执行、端口监听这一整条链路。

第三步：理解 package.json

打开项目根目录的 package.json，它是整个项目的说明书。需要看懂的部分包括：

• scripts：定义了 dev、build、preview 这类命令，你日常执行的就是它们。
• dependencies：运行时需要的包，比如 React、路由库。
• devDependencies：只在开发和构建阶段需要的包，比如 TypeScript、构建工具。
• name、version、private 等元信息字段。

对技术写作者来说，读懂 package.json 是一项基础能力。当你在客户仓库里看到这个文件，就能快速判断项目用什么框架、怎么启动、怎么构建。

第四步：组织路由文件

路由决定了 URL 与页面之间的对应关系。使用基于文件的路由方案时，目录结构本身就表达了站点结构。典型形态如下：

src/
  routes/
    __root.tsx
    index.tsx
    projects.tsx
    writing.tsx
    about.tsx
  components/
  assets/
  lib/
  styles/

每个路由文件导出一个页面组件。根路由文件负责包裹全局布局，比如导航栏和页脚。理解路由的关键在于能回答：这个 URL 对应哪个文件？页面之间怎么跳转？共享布局放在哪里？

第五步：把界面拆成组件

React 的核心是组件化。不要把整个网站塞进一个巨大的 HTML 文件，而是拆成可复用的片段：

• 导航组件：在多个页面之间复用。
• 按钮组件：全站统一外观。
• 项目卡片组件：用一份组件代码渲染多个项目，而不是复制多份标记。

这件事从文档角度看同样有价值。当你理解了组件化开发，就会开始用「可复用概念、依赖、输入、输出、行为」来思考文档结构——而这正是开发者关心的东西。

第六步：用 TypeScript 定义数据契约

TypeScript 为 JavaScript 增加了静态类型。对作品集项目来说，你可以说它并非必需，但使用它反映了你预期会遇到的开发环境，也迫使你想清楚数据在组件和函数之间流动时的形状。例如：

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

这段代码给「一个项目包含什么」下了明确契约。这种思维方式可以直接迁移到技术文档：写 API 文档时，你本质上就是在记录契约——输入、输出、类型、必填字段、可选字段、错误、预期行为。

第七步：处理静态资源

资源文件也是文档叙事的一部分。截图、示意图、示例数据文件、图标，都应该有明确的存放位置和命名规则。把资源随手丢在根目录，会让项目在几个月后变得难以维护，也会让协作者无从下手。

第八步：整理配置文件

配置文件决定了构建行为、样式处理、类型检查规则。它们通常包括构建工具配置、样式配置、TypeScript 配置等。你不需要背下每一项，但要能回答：改样式在哪里改？改构建输出在哪里改？类型检查严格程度在哪里调？

第九步：把 AI 用在正确的位置

AI 改变了写作方式，但结论不是「技术写作者应该回避 AI」，而是「应该换一种用法」。AI 擅长处理重复性工作：生成初稿大纲、提供替代解释、简化复杂句子、找出可能的边界情况、把笔记转成初稿、生成测试用例、解释不熟悉的语法、审阅结构、头脑风暴示例、比较不同方案。

但有一条界限必须守住：AI 可以加速思考，不能替代你对正确性的责任。如果 AI 生成了一个 Node.js 示例，你要把它跑一遍；如果它解释了一个 API，你要拿解释和实际实现或官方文档对照；如果它给出一条命令，你要真的执行一次；如果它生成了一篇教程，你要像读者一样从头到尾走一遍。

这样，AI 的角色就从「帮我写这篇文章」变成了「帮我调查、测试、质疑并改进这篇文章」。

第十步：部署到静态托管平台

把代码推送到 GitHub 仓库，然后在托管平台连接该仓库，配置构建命令与发布目录。构建命令通常是 npm run build，发布目录由构建工具决定，需要以实际输出为准。配置完成后，每次推送到主分支都会触发一次自动构建与发布。

部署这一步本身就是作品集的一部分：它证明你能把本地代码变成线上可访问的产物。

一个完整示例

下面走一遍从零到上线的最小流程。

1. 创建项目

npm create vite@latest my-portfolio -- --template react-ts
cd my-portfolio
npm install

2. 安装样式与图标依赖

npm install tailwindcss lucide-react

3. 定义项目数据类型

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

export const projects: Project[] = [
  {
    title: "面向开发者的技术写作作品集",
    description: "用 React、TypeScript、TanStack Start、Tailwind CSS 构建，并配有部署工作流。",
    technologies: ["React", "TypeScript", "Tailwind CSS"],
    url: "/projects/portfolio",
  },
];

4. 写一个可复用的项目卡片组件

import type { Project } from "../lib/projects";

export function ProjectCard({ project }: { project: Project }) {
  return (
    <article>
      <h3>{project.title}</h3>
      <p>{project.description}</p>
      <ul>
        {project.technologies.map((tech) => (
          <li key={tech}>{tech}</li>
        ))}
      </ul>
    </article>
  );
}

5. 在页面里渲染列表

import { projects } from "../lib/projects";
import { ProjectCard } from "../components/ProjectCard";

export function ProjectsPage() {
  return (
    <section>
      <h2>项目</h2>
      {projects.map((project) => (
        <ProjectCard key={project.title} project={project} />
      ))}
    </section>
  );
}

6. 本地验证

npm run dev
npm run build
npm run preview

三个命令都要跑通：开发模式看效果，构建模式看是否报错，预览模式看构建产物是否正常。

7. 提交并推送

git init
git add .
git commit -m "初始化技术写作作品集"
git branch -M main
git remote add origin <你的仓库地址>
git push -u origin main

8. 连接托管平台

在托管平台新建站点，选择该仓库，填入构建命令与发布目录，保存后触发首次部署。部署完成后访问分配的域名，确认页面正常。

注意事项

不要罗列你无法演示的技术。技术清单越长，定位越模糊。只写你能当场打开仓库、跑起示例、解释清楚的那些。

项目描述不要写成技术名词堆砌。「React 作品集网站」几乎不传达信息。要写清问题、产物、技术和它证明了什么。

AI 生成的内容必须验证。代码要跑，命令要执行，API 说明要和实现或官方文档对照，教程要像读者一样从头走一遍。这一步不能省。

不要只写「已发表 N 篇文章」。把文章本身展示出来，给读者一个能亲自检查你工作的入口。

结尾要有具体动作。「有需求请联系我」太弱，给出一个对方可以立刻执行的具体提议。

价格、配额、版本、地区可用性这类信息会变。涉及这些内容时，一律以相关平台官网当前信息为准，不要依赖本文或任何二手描述。

作品集的真正考验只有一个：访客能不能在几分钟内判断出你确实能独立调查、构建、测试并解释技术。如果做不到，再漂亮的页面也只是在线简历。