Redian新闻
>
文档并不是开源项目开发的附属品 | Linux 中国

文档并不是开源项目开发的附属品 | Linux 中国

科技
 
导读:有些项目长期保持活跃,有些项目却过早消亡 —— 这两者的区别往往在于它们的文档。严谨、聪明的文档可以给你的项目带来它所需要的动力。
本文字数:3032,阅读时长大约:5分钟

LCTT 译者 :六开箱
🌟🌟🌟🌟
翻译: 43.0 篇
|
贡献: 50 天
2022-03-16
2022-05-04
https://linux.cn/lctt/lkxed

有些项目长期保持活跃,有些项目却过早消亡 —— 这两者的区别往往在于它们的文档。严谨、聪明的文档可以给你的项目带来它所需要的动力。你应该把文档工作视为一项主要工作,把它与开发相提并论,下面我将说明这么做的理由和正确的做法。

经常会有开发者简单地认为他们的代码的“自我描述(self-documented)”已经足够了,继而认为额外的文档是没有必要的。这种过度的自信会让项目付出很大的代价。匮乏或差劲的文档会扼杀你的项目。没有适当的文档,用户将无法理解项目的目标以及正确的工作流程。这可能会导致人们对采用你的开源产品产生一些疑虑。

撰写文档,从项目第一天就开始

文档不应该是次要的工作,它应该是与代码开发和管理同等的主要任务。随着内容以 Community Threads、Stack Overflow 和 Quora 问答等形式的广泛传播,文档承担了“信息源(source of truth)”的角色。它应该满足那些想参考一手资料的贡献者的需要,并给工程师提供必要的参考支持。它还应该与利益相关者沟通基本计划。一个好的文档可以确保产品的持续改进和发展。

当发布一个软件产品时,我们不仅要发布代码,还要发布好的文档。这给我们带来了一个最重要的概念,大多数良好维护了文档的开源项目都遵循这个概念 —— “文档即代码(Documentation as code)”。

文档及代码

今天,文档不再被存储为微软 Word 或 PDF 文件。新的需求是版本控制文档,其中所有的文档都是通过版本控制系统添加的,并持续发布。这个概念因 Read the Docs(LCTT 译注:一个文档创建、托管和浏览的平台)而流行,现在已经成为大多数文档团队的内容策略的重要组成部分。

像 Bugzilla 和 GitHub 议题(Issue)这样的工具可以用来跟踪待处理的文档工作,并从维护者和用户那里获得反馈以验证文档的发布。外部审查可以用来验证文档作品,并持续发布文档。这就保证了除代码外,文档也能不断改进并快速发布。

请记住,如果不遵循规范化的实践,每个文档都会不同。这可能会导致一些混乱,使人们难以获取正确的信息。

哪些东西会被归类为混乱呢?当大多数文件都不遵循规范实践时,不一致就会产生,从而导致更大的混乱!那么,如何整理混乱的开源文档呢?

整理混乱的开源文档

遵循一个“文档风格指南”是很重要的。风格指南是创建和展示内容的指导方针的集合。无论你是一个独立的作家还是一个大型文档团队的成员,它都有助于在你的文档中保持一致的风格、口音和语气。

有几个流行的风格指南,如《红帽风格指南》、《谷歌文档风格指南》和《苹果风格指南》。如何选用?首先要从定义你的需求开始。如果你的要求与其他开源项目没有太大区别,你可以遵循一个现成的风格指南,或者你也可以先选一个,然后在它的基础上根据自身需要做一些修改。大多数与语法有关的准则和内容规则可能是通用的,但整体术语可能会有所不同。

你还需要在你的项目中自动采用这些风格指南。为此,你可以使用 Vale,它集成了本地的持续集成(CI)服务,该服务能帮助你确保文档严格遵循风格指南。

文档类型

◈ 自述文件:包含基本的安装和使用说明,这也是任何开源文档中最重要的部分之一。它是潜在的用户/开发者与项目之间的第一个连接点。
◈ 参考指南:可能包括一些基本的参考资料,以便帮助你快速上手,或者是与项目贡献相关的文档。
◈ 用户文档:是最基本的文档,它描述了项目的使用方式。如果没有用户文档,大多数人就会对如何使用该项目感到迷茫。
◈ 开发文档:旨在支持开发团队在项目中不断取得新的进展。它还应该为内部开发工作提供一个良好的途径,并确保功能被很好地传达给股东。
◈ 社区内容:包括基本的博客、视频和外部内容,旨在为那些想进一步了解项目的社区成员提供支持。

通过使用风格指南,文件的整体前提将以统一的语言风格传达给用户。但是,这些文件毕竟是由一个技术作家团队准备的,它们的写作风格可能会冲突,因为写作风格是因人而异的。那么,如何才能使文档规范化呢?

规范化文档

当涉及到规范化文档时,有许多方法可以采取。第一个方法显然是创建适用于各种角色的预定义模板。这些模板可以用来记录新的功能、识别错误和问题,以及更新变更日志以适应正在增加的新内容。

如果你采用的是基于 Git 的工作流,试着开发一个规范的工作流程来发布你的文档。最规范的工作流是:复刻(fork) 发布文档的仓库,在本地分支上添加你的修改,推送这些修改,提出请求并要求对其进行审查。规范化文档的一个好处就是带来更好的反馈和审查过程。

反馈和自动审查

规范化使得你能够得到用户的反馈并生成自动的审查,可以参考这些反馈来改进项目和文档。通过这些反馈,你也可以评估所分享的信息对用户是否有意义。像 GitBook 这样的文档平台会提供合适的反馈服务,这有助于验证文档是否有用。

始终寻求主题专家(subject matter expert)(SME)对文档的反馈,他们可以是利益相关者、开发者、工程师,甚至是外部贡献者。你也可以使用自动测试和 CI 来验证你的文档是否遵循风格指南。

文档众包

如果你想开源你的文档,最好的方法也许是提供一个快速入门指南。它可以像 CONTRIBUTING.md 那样简单,基本上只要说明该如何设置项目并为其作出贡献/单纯使用它即可。

始终开发以用户为中心的文档,标明每个项目的目的。同时,打造学习课程来帮助新的贡献者。

带着目的编写文档

始终带着目的编写文档。它是最基本的写作策略之一,它定义了你编写某个特定文档的理由,而非方式。首先回答以下问题:

◈ 这个文档的目标是什么?
◈ 需要传递的信息是什么?
◈ 你希望用户在这之后采取什么行动?
◈ 我与读者分享的价值观是什么?
◈ 我的文档风格是否简洁、一致?

定义一致的内容策略

一致的内容策略有助于确保文档工作和项目基础设施的长期愿景。它可以围绕以下两个主要方面:

1. 资源:包括项目文档、案例研究和白皮书、项目架构等
2. 品牌内容:博客和特邀帖子、新闻和社区故事、学习课程等

每个开源项目都应该有适当的文档,以说明它能为用户提供的功能,这样用户就可以选择最合适的解决方案。适当的文档可以传达正确的信息,也可以让其他开发者贡献力量来进一步加强和改进项目。虽然听起来很简单,但只有做对了,文档才能成功。而你的项目,反过来,只有在你的文档正确的情况下才能成功,所以永远不要低估它的目标或过程!

策划:Laveesh Kocher


via: https://www.opensourceforu.com/2022/04/documentation-isnt-just-another-aspect-of-open-source-development/

作者:Harsh Bardhan Mishra 选题:lkxed 译者:lkxed 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出


欢迎遵照 CC-BY-SA 协议规定转载,
如需转载,请在文章下留言 “转载:公众号名称”,
我们将为您添加白名单,授权“转载文章时可以修改”。


微信扫码关注该文公众号作者

戳这里提交新闻线索和高质量文章给我们。
相关阅读
System76 与惠普合作为开发者提供功能强大的 Linux 笔记本电脑 | Linux 中国OpenInfra 基金会启动“定向资助”以支持开源项目 | Linux 中国开源朗读者:我为什么从 Mac 转到 Linux | Linux 中国Copilot免费时代结束!正式版67元/月,学生党和热门开源项目维护者可白嫖我如何在 Linux 上扫描家庭照片 | Linux 中国上一个说“丼”不读jǐng的人,已经被我骂哭了解决研发数据分析瓶颈,开源项目DevLake加入Apache软件基金会孵化器 | InfoQ专访俄乌恩仇,这老爷子所言不虚呀!小子的作品(三)Apache Kyuubi:一个有趣的大数据开源项目Archinstall 新的菜单系统让安装 Arch Linux 更容易了 | Linux 中国用这些开源工具在 Linux 上编辑 PDF 文件 | Linux 中国神奇的脚指操一块英伟达3090单挑180亿参数大模型,国产开源项目这回杀疯了使用 apt 进行 Linux 包管理 | Linux 中国普京的加速失败对全球化的影响使用 dnf 进行 Linux 包管理 | Linux 中国跟不上时代的老人有研究表明,推特能够推动开源项目的普及 | Linux 中国开源朗读者:开源新手指南 | Linux 中国在虚拟机中运行 Linux 的十大优点 | Linux 中国Linux 中国开通播客频道:“开源朗读者”和“硬核观察” | Linux 中国开源朗读者:在虚拟机中运行 Linux 的十大优点 | Linux 中国最适合程序员的 10 款 Linux 发行版 | Linux 中国如何在 Linux 桌面中启用 “激活 Linux” 水印通知 | Linux 中国开源朗读者:Linux 太难了?你需要知道这 5 点 | Linux 中国实测 Linux Mint 升级工具 | Linux 中国使用 Linux 上的开源财务工具 Skrooge 管理你的预算 | Linux 中国用 Gwenview 在 Linux 上裁剪和调整照片大小 | Linux 中国使用 watch 和 tail 命令监视 Linux 上的活动 | Linux 中国开源开发者创建首个支持维护者的基金 | Linux 中国如何在 Linux 和 Windows 电脑之间共享文件 | Linux 中国Linux Mint 接管 Timeshift 备份工具的开发,并作为一款 XApp 来维护 | Linux 中国微软加入开放 3D 基金会,参与开源 3D 开发 | Linux 中国开源朗读者:我是如何帮助妈妈从 Windows 切换至 Linux 的 | Linux 中国
logo
联系我们隐私协议©2024 redian.news
Redian新闻
Redian.news刊载任何文章,不代表同意其说法或描述,仅为提供更多信息,也不构成任何建议。文章信息的合法性及真实性由其作者负责,与Redian.news及其运营公司无关。欢迎投稿,如发现稿件侵权,或作者不愿在本网发表文章,请版权拥有者通知本网处理。