Skip to content
LightCMS logo
Search Documentation
Search all documentation articles and topics

2027年管理文档的最佳方法

文件是每个人都同意的项目的一部分,没有人完全同意如何处理。看看五个开源项目,你会找到五个不同的设置。有些进展良好。最容易变成疏忽。 这里是共同模式实际上是什么样子,为什么有些模式随着时间的推移而比其他模式好一些。 ## Wiki 方式:快速启动,慢慢拨到Die GitHub wikis和汇流是许多团队的默认。

文件是每个人都同意的项目的一部分,没有人完全同意如何处理。看看五个开源项目,你会找到五个不同的设置。有些进展良好。最容易变成疏忽。

这里是共同模式实际上是什么样子,为什么有些模式随着时间的推移而比其他模式好一些。

Wiki 方式:快速启动,慢慢拨到Die

GitHub wikis和汇流是许多团队的默认。他们快速设置,不需要配置,任何人都可以添加一个页面。

问题是wikis累积的页面比它们保持的速度快。两年制项目的汇合空间通常有准确的网页。 页面已过时,也没有可靠的方法来告诉哪个是脂肪。搜索表面等值。没有审查过程。没有人拥有任何东西。

GitHub wikis在添加约束时遇到同样的问题:他们生活在一个与你的代码分开的仓库中。更改API的拉取请求不会自动提示任何人更新文档。代码和文档之间的差距无声地扩大。

使用维基的团队是个例外。它们通常有专门的技术作者执行标准。大多数队伍不存在。

概念和类似的工具:对内部团队非常棒,寿命较长

对于内部文档——登载指南、运行簿、团队流程、会议笔记——来说,概念是真正很好的。编辑器是灵活的,权限是粒子化的,它很容易让非技术性贡献者实际上使用它。

对于与代码并存的项目文件,它在几个方面都有欠缺。

您的文档位于Notion's database,不在您的资源库中。没有差异、没有审查报告、没有自动部署。如果概念改变定价,放弃某个功能,或者干脆离开,移徙就是手动导出和重新安排工作。

更深刻的问题是可发现性。生活在Notion 中的文档没有与您的代码组合一起索引。为函数名称翻修的开发者不会找到解释其工作方式的概念页面。这两个系统不能相互交谈。

README驱动:诚实但难以缩放

许多较小的项目——以及许多开放源码项目——几乎完全依靠README。一个文件保持当前状态,包括安装、使用和贡献准则。

对于一个稳定的 API 的重点突出的工具,这种情况令人吃惊。一个文件力优先级的限制。没有任何文件喷洒,因为没有任何地方可以去做。

当一个项目经过某种复杂性时,它就会破裂。包含15个不同配置选项、三个部署目标的README,以及一个从 v1 到 v2 停止的迁移指南。当时的团队要么让它腐烂,要么开始建造其他东西。

Docs-as-code:缩放模式

文档一贯良好的项目往往使用相同的基本模式:在仓库中Markdown文件。 由静态站点生成器构建,每次发布都同时部署。

Kubernetes 文档与codebase处于同一个单一orepo中,在同一个合并请求工作流程中进行了审核。 Rust Book 是GitHub 上的一个Markdown 项目,有数百个贡献者。 Astro的文件是Astro Starlight 站点,与框架本身并肩投入使用。

做这个工作的不是工具。这是工作流程。文档在代码旁边运行,所以当代码更改时他们会得到更新。添加一个新标志的PR 需要在合并前更新文档。审查过程强制执行。

二级津贴是耐久性。 2015年Markdown文件仍然可以读取,可在2027年部署。无迁移需要,不需要专有导出格式,不需要平台依赖性。内容只是文件夹中的文本文件。

杀死文档作为非技术贡献者代码的摩擦力

Markdown in Git方法的一个真正弱点是,它假定每个人都对文本编辑器和拉取请求感到满意。对许多团队来说,这是很好的。对于非技术性贡献者的团队——营销、产品、支持——来说,它造成摩擦,导致在平行系统中忽略或维持博士学位。

这是Git支持的 CMS 适合使用的地方。 LightCMS等工具坐在仓库前面,让贡献者在仍然将Markdown文件提交到仓库时有真正的编辑体验。编辑器处理格式化。 CMS处理提交。贡献者从未看到终端。

结果与 docs-as code -in Markdown, 版本在 Git. 由您现有的管道部署——但不想直接使用 Git 的人可以访问。

什么实际工作于2027年

挂起的模式很简单:将Markdown文件放在你的仓库中,由静态站点生成器构建,在合并请求中复核。

围绕这一模式的具体工具不如工作流程重要。如果你的团队使用 GitHub,那么一个致力于同一个仓库的Starlight 或 Docusaurus 网站将给你所有的东西:搜索, 版本、正确的阅读体验,以及使文档与代码同步的审核过程。

如果您有非技术贡献者,请先放置一个 Git 支持的编辑器,这样他们就可以在不触摸终端的情况下写入。基础设置保持不变。内容停留在您的仓库中。

具有最佳文件记录的项目不是最好的工具。他们是那些使文档与代码相同的工作流程的一部分的人。


常见问题

什么是 docs-as code?

Docs-as code 是使用与软件开发相同的工具和工作流编写和维护文档的做法:纯文本文件(通常是Markdown) 版本控制 (通常是 Git),代码审核和自动部署。它将文档保持在它描述的代码附近,并将更新作为正常的开发工作流程的一部分。

Markdown是否能够让文档化?

是的,对绝大多数项目都是如此。 Markdown 处理标题、代码块、表、图像和链接。 Starlight、Docusaurus和MkDocs等静态站点发电机增加了搜索、导航、版本控制和适当的顶部阅读体验。纯文本的约束是一个功能:它可以在任何编辑、贪婪、可传播和持续数十年的时间里读取。

非技术作者如何贡献Markdown 文档?

Git-backed CMS工具,例如LightCMS提供一个丰富的编辑器,将Markdown 提交给你的资源库,而不要求贡献者直接使用Git。内容停留在你的仓库中,在普通Markdown中。编辑器只是一个更易于访问同一基本文件的接口。

什么是文档的最佳静态站点生成器?

取决于您的堆栈。 Astro Starlight 和 Docusaurus 是最全功能的选项,并可从箱子中搜索。拥有材料的MkDocs对于Python项目来说是很好的。如果你已经在 Hugo 或 Eleventy 上博客,他们也可以处理文档。生成器比将文档保留在与您的代码相同的仓库中更重要。

enafarcacsdadeelesfifrhehuitjakonlnoplptpt-BRrorusrsvtrukvizh-CNzh-TW