本篇文章思考了为什么要建立前端文档，以及用什么样的形式去建设前端文档。后续会尝试整理出针对不同类型的文档的建设方案。
前端文档建立的考量点
为什么要建立前端文档，并将其视为一个前端基础建设？
- 帮助快速熟悉项目、融入团队
- 作为团队的知识沉淀，知识传递，防止断档
- 将技术知识固化共享
- 利于项目的可维护性
- 更好的理解和沟通，提高效率
前端文档需要写什么？
从文档内容去考虑的话，主要有以下类型的文档：
这里主要从两个方面去考虑文档的内容：
- 从团队角度（下文以知识库文档代指此类文档）
- 新人文档（工具、资源的开通）
- 研发流程
- 约定俗成
- 规范文档
- 各类技术规范
- 代码规范
- 各类技术类文档（大部分应该是会通过项目中沉淀下来）
- 从开发角度（下文以项目文档代指此类文档）
- 业务项目文档
- 公共库、组件库文档
知识库文档是面向整个团队的，这些文档的建立，是为了能够沉淀出针对某个方面有价值、能够受益于整个团队成员的知识内容。
而文档的内容和项目本身息息相关的文档则是项目文档，这种文档的目的是为了让不了解的人能快速了解、熟悉这个项目。
文档建设有哪方面的考量？
不管是知识库文档还是项目文档都有以下几点共性：
- 文档需要易于维护性
- 语法格式统一
- 协作性
- 文档内容要保持时效性
- 及时维护
- 文档内容便于查找
- 清晰的文档目录结构
- 特定类别文档的模板（组件库、npm包）
除此之外，对于知识库文档来说，其重点面向的是所有团队成员，所以其文档建设会更加偏向于在线协作和知识分享等特性。
而项目文档因为和某个具体的项目具有较强的耦合，且其维护通常会伴随项目的更新迭代，所以，它更加适合同项目本身放在一起。
如何建立？
根据文档类型的特点，我考虑将知识库文档建立在在线协作平台上面，类似于飞书知识库、语雀这种，而项目文档则直接和项目源码维护在一起。
知识库文档：在线协作平台
因为我们公司办公用的飞书，所以自然想到的是将知识库文档维护在飞书知识库，所以这里以它为例，其他在线协作平台（比如语雀）的特点也是差不多的：
- 在线文档
- 多人协作
- 丰富的内容形式：强大的表格、思维导图、流程图、其他扩展内容等强大的功能，以多种形式，让你更好的表现知识内容。
它的缺点是：
- 受限平台：文档语法格式的兼容、迁移问题（可能存在）
至少以飞书知识库来说，目前（2022.5）飞书知识库都无法进行迁移到飞书自己其他组织下的知识库，也无法导出markdown，如果文档需要迁移了，那么会是个非常大的麻烦。
项目文档：markdown文件
这里的项目文档不止是包含了业务项目中的文档，同时也包含了组件库、npm公共包等包项目文档。而且，发布到npm上面的包所包含的文档还和业务项目文档有所差别。
对于开发来说，写项目文档通常会直接写markdonw，并将markdown文件和项目源码放在一起。
业务项目文档
如果是简单的业务项目，那么一个README.md可能就足矣，然而，事实远没有那么简单，通常一个较为复杂的项目，其文档包含的内容是涵盖许多方面的，这时候你需要建立一个专门的docs目录来存放和组织你的项目文档。
而如果你还想要将文档发布到线上，那么可以考虑使用docsify这种在线生成文档网站的工具。
使用markdonw编写文档的好处呢是不受平台限制，且语法通用，这对于迁移来说是比较友好的。
它的缺点也很明显：
- 纯粹的markdown的表现力没有在线协作平台那样丰富
- 文档的多人协作问题
- 如果文档需要发布到线上，还需要额外的部署
库文档
这里的库文档，包含了公共npm包、组件库这种类型项目的文档。通常这些文档的介绍不会特别复杂，当然，即使复杂也能接受写在一个README.md文件里面，因为npm仓库就只认一个README.md文件作为文档。（当然，你也可以使用docsify这种工具来更好的组织你的文档）
而这些库文档，通常还会包含另外的一种文档：如果是公共npm包这种，会包含API文档，而如果是组件库，则会包含UI组件文档，而这两种都有专门的工具来生成，不过肯定是需要你将这些文档发布到线上的。
总结
其实这里不仅仅只是限于前端，对于一个公司的整个开发团队来说，文档的沉淀是团队的财富。当然，对于一个团队来说，我们不只是在开头建立起团队文档就够了，还需要后续培养团队的文档氛围，让团队的每个成员都能受益于文档，同时也自愿维护文档，贡献文档。这样，团队的文档才能慢慢沉淀下来，变成真正的财富。