为什么需要搭建文档网站
为什么需要搭建文档网站
Section titled “为什么需要搭建文档网站”在深入工具和代码之前，让我们先回答一个根本问题：为什么要投入时间和精力搭建专门的文档网站？本节将探讨自托管文档在商业和技术层面的动因。
Q：为什么不直接用 Wiki 或共享文档（Notion、Confluence、飞书文档）？
Section titled “Q：为什么不直接用 Wiki 或共享文档（Notion、Confluence、飞书文档）？”A：Wiki 和共享文档在内部协作中表现出色，但在面向外部的文档场景中存在明显短板：
| 关注点 | Wiki / 共享文档 | 独立文档站 |
|---|---|---|
| SEO 与可发现性 | 搜索引擎极少索引内部文档 | 完全可索引，带来自然流量 |
| 版本控制 | 手动追踪历史 | Git 原生，每次变更都有版本记录 |
| 品牌定制 | 受限或无法定制 | 完全控制外观与体验 |
| 离线访问 | 需要联网 | 可导出或缓存（PWA） |
| 搜索 | 基础关键词搜索 | Pagefind、Algolia 等全文搜索 |
| 性能 | 大型文档加载慢 | 静态 HTML，毫秒级加载 |
| 多语言 | 手动复制 | 结构化 i18n，按语言路由 |
对于纯内部笔记，Wiki 就够了。但如果文档是产品价值主张的一部分——无论是教程、API 参考还是知识库——都值得搭建专门的站点。
Q：文档网站对小型 IoT 公司有什么帮助？
Section titled “Q：文档网站对小型 IoT 公司有什么帮助？”A：对于销售硬件 + 软件方案的 IoT 公司，文档承担多重战略角色：
- 售前：潜在客户将文档质量视为产品质量的代理指标。结构清晰的教程传递专业感。
- 新手引导：在客户提问之前就回答常见的安装问题，减少支持工单。
- 用户留存：能够自助服务的用户更倾向于留在你的生态中。
- 知识库：内部团队成员参考同样的文档，形成单一信息源。
- SEO 漏斗：技术博客和教程吸引开发者，其中部分人会转化为客户。
Q：维护文档网站的持续成本是多少？
Section titled “Q：维护文档网站的持续成本是多少？”A：采用静态站点方案（如 Astro + Starlight），成本非常低：
- 托管：在 Vercel、GitHub Pages、Netlify 或 Cloudflare Pages 等平台免费
- 域名：自定义域名（如
docs.yourcompany.com）约 ¥70-100/年 - 维护：内容更新融入日常开发工作流
- 构建时间：静态站点即使有数百页也在秒级完成构建
主要成本是编写和维护内容的时间投入——但这是你无论如何都需要花在回答支持问题上的时间。
Q：什么时候是搭建文档网站的最佳时机？
Section titled “Q：什么时候是搭建文档网站的最佳时机？”A：理想时机是当你拥有：
- 至少一个他人需要使用的项目或产品
- 5 页以上的内容（即使部分是占位符）
- 基于 Git 的开发工作流
- 愿意将文档作为一等交付物来对待
不需要等到所有内容”写完”。从小处开始，尽早发布，持续迭代。我们将使用的框架（Astro + Starlight）让添加新页面变得极为简单。
下一节我们将评估主流的文档框架，并解释为什么为本项目选择了 Astro + Starlight。
正在开发商业 IoT 产品？
我们提供 ESP32 ODM 定制设计与制造服务。从原型到量产——编写这套教程的团队，可以和你一起实现。
联系我们 →