mirror of
https://github.com/LCTT/TranslateProject.git
synced 2024-12-26 21:30:55 +08:00
Merge pull request #25483 from wxy/20220422-Documentation-Isn’t-Just-Another-Aspect-of-Open-Source-Development
RP:20220422 documentation isn’t just another aspect of open source development
This commit is contained in:
Xingyu.Wang
GitHub
commit
2e5d95d247
@ -0,0 +1,105 @@
|
||||
[#]: subject: "Documentation Isn’t Just Another Aspect of Open Source Development"
|
||||
[#]: via: "https://www.opensourceforu.com/2022/04/documentation-isnt-just-another-aspect-of-open-source-development/"
|
||||
[#]: author: "Harsh Bardhan Mishra https://www.opensourceforu.com/author/harsh-bardhan-mishra/"
|
||||
[#]: collector: "lkxed"
|
||||
[#]: translator: "lkxed"
|
||||
[#]: reviewer: "wxy"
|
||||
[#]: publisher: "wxy"
|
||||
[#]: url: "https://linux.cn/article-14545-1.html"
|
||||
|
||||
文档并不是开源项目开发的附属品
|
||||
======
|
||||
|
||||
有些项目长期保持活跃，有些项目却过早消亡 —— 这两者的区别往往在于它们的文档。严谨、聪明的文档可以给你的项目带来它所需要的动力。你应该把文档工作视为一项主要工作，把它与开发相提并论，下面我将说明这么做的理由和正确的做法。
|
||||
|
||||
|
||||
|
||||
经常会有开发者简单地认为他们的代码的“<ruby>自我描述<rt>self-documented</rt></ruby>”已经足够了，继而认为额外的文档是没有必要的。这种过度的自信会让项目付出很大的代价。匮乏或差劲的文档会扼杀你的项目。没有适当的文档，用户将无法理解项目的目标以及正确的工作流程。这可能会导致人们对采用你的开源产品产生一些疑虑。
|
||||
|
||||
### 撰写文档，从项目第一天就开始
|
||||
|
||||
文档不应该是次要的工作，它应该是与代码开发和管理同等的主要任务。随着内容以 Community Threads、Stack Overflow 和 Quora 问答等形式的广泛传播，文档承担了“<ruby>信息源<rt>source of truth</rt></ruby>”的角色。它应该满足那些想参考一手资料的贡献者的需要，并给工程师提供必要的参考支持。它还应该与利益相关者沟通基本计划。一个好的文档可以确保产品的持续改进和发展。
|
||||
|
||||
当发布一个软件产品时，我们不仅要发布代码，还要发布好的文档。这给我们带来了一个最重要的概念，大多数良好维护了文档的开源项目都遵循这个概念 —— “<ruby>文档即代码<rt>Documentation as code</rt></ruby>”。
|
||||
|
||||
### 文档及代码
|
||||
|
||||
今天，文档不再被存储为微软 Word 或 PDF 文件。新的需求是版本控制文档，其中所有的文档都是通过版本控制系统添加的，并持续发布。这个概念因 Read the Docs（LCTT 译注：一个文档创建、托管和浏览的平台）而流行，现在已经成为大多数文档团队的内容策略的重要组成部分。
|
||||
|
||||
像 Bugzilla 和 GitHub <ruby>议题<rt>Issue</rt></ruby>这样的工具可以用来跟踪待处理的文档工作，并从维护者和用户那里获得反馈以验证文档的发布。外部审查可以用来验证文档作品，并持续发布文档。这就保证了除代码外，文档也能不断改进并快速发布。
|
||||
|
||||
请记住，如果不遵循规范化的实践，每个文档都会不同。这可能会导致一些混乱，使人们难以获取正确的信息。
|
||||
|
||||
哪些东西会被归类为混乱呢？当大多数文件都不遵循规范实践时，不一致就会产生，从而导致更大的混乱！那么，如何整理混乱的开源文档呢？
|
||||
|
||||
### 整理混乱的开源文档
|
||||
|
||||
遵循一个“文档风格指南”是很重要的。风格指南是创建和展示内容的指导方针的集合。无论你是一个独立的作家还是一个大型文档团队的成员，它都有助于在你的文档中保持一致的风格、口音和语气。
|
||||
|
||||
有几个流行的风格指南，如《红帽风格指南》、《谷歌文档风格指南》和《苹果风格指南》。如何选用？首先要从定义你的需求开始。如果你的要求与其他开源项目没有太大区别，你可以遵循一个现成的风格指南，或者你也可以先选一个，然后在它的基础上根据自身需要做一些修改。大多数与语法有关的准则和内容规则可能是通用的，但整体术语可能会有所不同。
|
||||
|
||||
你还需要在你的项目中自动采用这些风格指南。为此，你可以使用 Vale，它集成了本地的持续集成（CI）服务，该服务能帮助你确保文档严格遵循风格指南。
|
||||
|
||||
> **文档类型**
|
||||
>
|
||||
> * *自述文件*：包含基本的安装和使用说明，这也是任何开源文档中最重要的部分之一。它是潜在的用户/开发者与项目之间的第一个连接点。
|
||||
> * *参考指南*：可能包括一些基本的参考资料，以便帮助你快速上手，或者是与项目贡献相关的文档。
|
||||
> * *用户文档*：是最基本的文档，它描述了项目的使用方式。如果没有用户文档，大多数人就会对如何使用该项目感到迷茫。
|
||||
> * *开发文档*：旨在支持开发团队在项目中不断取得新的进展。它还应该为内部开发工作提供一个良好的途径，并确保功能被很好地传达给股东。
|
||||
> * *社区内容*：包括基本的博客、视频和外部内容，旨在为那些想进一步了解项目的社区成员提供支持。
|
||||
|
||||
通过使用风格指南，文件的整体前提将以统一的语言风格传达给用户。但是，这些文件毕竟是由一个技术作家团队准备的，它们的写作风格可能会冲突，因为写作风格是因人而异的。那么，如何才能使文档规范化呢？
|
||||
|
||||
### 规范化文档
|
||||
|
||||
当涉及到规范化文档时，有许多方法可以采取。第一个方法显然是创建适用于各种角色的预定义模板。这些模板可以用来记录新的功能、识别错误和问题，以及更新变更日志以适应正在增加的新内容。
|
||||
|
||||
如果你采用的是基于 Git 的工作流，试着开发一个规范的工作流程来发布你的文档。最规范的工作流是：<ruby>复刻<rt>fork</rt></ruby> 发布文档的仓库，在本地分支上添加你的修改，推送这些修改，提出请求并要求对其进行审查。规范化文档的一个好处就是带来更好的反馈和审查过程。
|
||||
|
||||
### 反馈和自动审查
|
||||
|
||||
规范化使得你能够得到用户的反馈并生成自动的审查，可以参考这些反馈来改进项目和文档。通过这些反馈，你也可以评估所分享的信息对用户是否有意义。像 GitBook 这样的文档平台会提供合适的反馈服务，这有助于验证文档是否有用。
|
||||
|
||||
始终寻求<ruby>主题专家<rt>subject matter expert</rt></ruby>（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][a]
|
||||
选题：[lkxed][b]
|
||||
译者：[lkxed](https://github.com/lkxed)
|
||||
校对：[wxy](https://github.com/wxy)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://www.opensourceforu.com/author/harsh-bardhan-mishra/
|
||||
[b]: https://github.com/lkxed
|
||||
[1]: https://www.opensourceforu.com/wp-content/uploads/2022/03/Importance-of-documentation-696x477.jpg
|
||||
@ -1,104 +0,0 @@
|
||||
[#]: subject: "Documentation Isn’t Just Another Aspect of Open Source Development"
|
||||
[#]: via: "https://www.opensourceforu.com/2022/04/documentation-isnt-just-another-aspect-of-open-source-development/"
|
||||
[#]: author: "Harsh Bardhan Mishra https://www.opensourceforu.com/author/harsh-bardhan-mishra/"
|
||||
[#]: collector: "lkxed"
|
||||
[#]: translator: "lkxed"
|
||||
[#]: reviewer: " "
|
||||
[#]: publisher: " "
|
||||
[#]: url: " "
|
||||
|
||||
文档并不是开源项目开发的附属品
|
||||
======
|
||||
有些项目长期保持活跃，有些项目却过早消亡 —— 这两者的区别往往在于它们的文档。严谨、聪明的文档可以给你的项目带来它所需要的动力。你应该把文档工作视为一项主要工作，把它与开发相提并论，下面我将说明这么做的理由和正确的做法。
|
||||
|
||||
![文档的重要性][1]
|
||||
|
||||
经常会有开发者简单地认为他们的代码已经足够“<ruby>自我记录<rt>self-documented</rt></ruby>”了，继而认为额外的文档是没有必要的。这种过度的自信会让项目付出很大的代价。不足或不好的文档会扼杀你的项目。没有适当的文档，用户将无法理解项目的目标以及正确的工作流程。这可能会导致人们对采用你的开源产品产生一些疑虑。
|
||||
|
||||
### 撰写文档，从项目第一天就开始
|
||||
|
||||
文档不应该是次要的工作，它应该是与代码开发和管理同等的主要任务。在 Community Threads、stack overflow 和 Quora 问答等社区中，文档内容广泛传播，其本身承担了“<ruby>信息源<rt>source of truth</rt></ruby>”的角色。 它应该满足那些想参考一手资料的贡献者的需要，并给工程师提供必要的参考支持。它还应该与股东沟通基本计划。一个好的文档可以确保产品的持续改进和发展。
|
||||
|
||||
当发布一个软件产品时，我们不仅要发布代码，还要发布好的文档。这给我们带来了一个最重要的概念，大多数维护着良好文档的开源项目都遵循这个概念 —— “文档即代码”。
|
||||
|
||||
### 文档及代码
|
||||
|
||||
今天，文档不再被存储为 Microsoft Word 或 PDF 文件。新的需求是版本控制文档，其中所有的文档都是通过版本控制系统添加的，并持续发布。这个概念因 Read the Docs（LCTT 译注：一个文档创建、托管和浏览的平台）而流行，现在已经成为大多数文档团队的内容策略的重要组成部分。
|
||||
|
||||
像 Bugzilla 和 GitHub Issues 这样的工具可以用来跟踪待处理的文档工作，并从维护者和用户那里获得反馈以验证文档的发布。外部审查可以用来验证文档作品，并持续发布文档。这就保证了除代码外，文档也能不断改进并快速发布。
|
||||
|
||||
请记住，如果不遵循任何规范化的实践，每个文档都会不同。这可能会导致一些混乱，使人们难以获取正确的信息。
|
||||
|
||||
哪些东西会被归类为混乱呢？当大多数文件都不遵循规范实践时，不一致就会产生，从而导致一个大混乱！那么，如何整理混乱的开源文档呢？
|
||||
|
||||
### 整理混乱的开源文档
|
||||
|
||||
遵循一个“文档风格指南”是很重要的。风格指南是创建和展示内容的指导方针的集合。无论你是一个独立的作家还是一个大型文档团队的成员，它都有助于在你的文档中保持一致的风格、声音和语气。
|
||||
|
||||
有几个流行的风格指南，如红帽风格指南，谷歌文档风格指南，和苹果风格指南。如何选用？首先要从定义你的需求开始。如果你的要求与其他开源项目没有太大区别，你可以遵循一个现成的风格指南，或者你也可以先选一个，然后在它的基础上根据自身需要做一些修改。大多数与语法有关的准则和内容规则可能是通用的，但整体术语可能会有所不同。
|
||||
|
||||
你还需要在你的项目中自动采用这些风格指南。为此，你可以使用 Vale，它集成了本地的持续集成（CI）服务，该服务能帮助你确保文档严格遵循风格指南。
|
||||
|
||||
### 文档类型
|
||||
|
||||
* 自述文件：包含基本的安装和使用说明，这也是任何开源文档中最重要的部分之一。它是潜在的用户/开发者与项目之间的第一个连接点。
|
||||
* 参考指南：可能包括一些基本的参考资料，以便帮助你快速上手，或者是与项目贡献相关的文档。
|
||||
* 用户文档：是最基本的文档，它描述了项目的使用方式。如果没有任何用户文档，大多数人就会对如何使用该项目感到迷茫。
|
||||
* 开发文档：旨在支持开发团队在项目中不断取得新的进展。它还应该为内部开发工作提供一个良好的途径，并确保功能被很好地传达给股东。
|
||||
* 社区内容：包括基本的博客、视频和外部内容，旨在为那些想进一步了解项目的社区成员提供支持。
|
||||
|
||||
通过使用风格指南，文件的整体前提将以统一的语言风格传达给用户。但是，这些文件是毕竟由一个技术作家团队准备的，它们的写作风格可能会冲突，因为写作风格是因人而异的。那么，如何才能使文档规范化呢？
|
||||
|
||||
### 规范化文档
|
||||
|
||||
当涉及到规范化文档时，有许多方法可以采取。第一个方法显然是创建适用于各种角色的预定义模板。这些模板可以用来记录新的功能、识别错误和问题，以及更新变更日志以适应正在增加的新内容。
|
||||
|
||||
如果你采用的是基于 Git 的工作流，试着开发一个规范的工作流程来发布你的文档。最规范的工作流是：<ruby>复刻<rt>fork</rt></ruby>发布文档的仓库，在本地分支上添加你的修改，推送这些修改，提出请求并要求对其进行审查。规范化文档的一个好处就是带来更好的反馈和审查过程。
|
||||
|
||||
### 反馈和自动审查
|
||||
|
||||
规范化使得你能够得到用户的反馈并生成自动的审查，这些反馈可以被考虑用来改进项目和文档。通过这些反馈，你也可以评估所分享的信息对用户是否有意义。像 GitBook 这样的文档平台会提供合适的反馈服务，这有助于验证文档是否有用。
|
||||
|
||||
始终寻求主题专家（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][a]
|
||||
选题：[lkxed][b]
|
||||
译者：[lkxed](https://github.com/lkxed)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://www.opensourceforu.com/author/harsh-bardhan-mishra/
|
||||
[b]: https://github.com/lkxed
|
||||
[1]: https://www.opensourceforu.com/wp-content/uploads/2022/03/Importance-of-documentation-696x477.jpg
|
||||
Loading…
Reference in New Issue
Block a user