document/TranslateProject
2
0
Fork 0
mirror of https://github.com/LCTT/TranslateProject.git synced 2025-01-13 22:30:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #25374 from lkxed/20220422-Documentation-Isn’t-Just-Another-Aspect-of-Open-Source-Development

Browse Source 
[提交译文][talk]: 20220422 Documentation Isn’t Just Another Aspect of Open Source Development.md
This commit is contained in:
Xingyu.Wang 2022-04-28 10:14:08 +08:00 committed by GitHub
commit 2d4040f99e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 104 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
sources/talk/20220422 Documentation Isn’t Just Another Aspect of Open Source Development.md
View File

@ -1,99 +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: " "
Documentation Isn’t Just Another Aspect of Open Source Development
======
Some projects live on, while some die a premature death – and the difference between the two often lies in the documentation. Meticulous, smart documentation can give your project the boost it needs. Here is why you should consider documentation a primary effort, on par with development, and the right way to go about it!
![Importance of documentation][1]
Often, developers simply assume that code is self-documented enough and doesn’t need any extra documentation. This overconfidence can cost the project a lot. Insufficient or bad documentation can kill your project. Without proper documentation in place users won’t be able to understand the purpose as well as the proper workflow of the project. That could lead to some apprehensions about adopting your open source product.
**Work on it, right from day one**
Documentation should never be a secondary effort; it should be a primary task on par with code development and management. Documentation acts as the definitive source of truth with the wide redistribution of content in the form of community threads, stack overflows, and quora answers. It should fulfil the need of contributors who would like to refer to the actual resource, and provide the necessary references to support engineers. It should also communicate essential plans with the stakeholders. A good documentation ensures continuous improvement and development of a product.
When releasing a software product, we must not only ship the code but good documentation as well. This brings us to one of the most important concepts that most open source projects with well-maintained documentation follow – ‘documentation as code’.
**Documentation as code**
Today documentation is not being stored in Microsoft Word or PDF files. The new need is version control documentation, wherein all the docs are added over a version control system and released continuously. This concept was popularised by ‘Read the Docs’ and has now become an essential part of the content strategy for most documentation teams.
Tools like Bugzilla and GitHub Issues can be used to track the documentation work that is pending, and take feedback from maintainers and users to validate the release of the documents. External reviews can be used to validate the documentation piece, and to continuously publish it. This ensures that not only code, but the documentation as well, is continuously improved and released quickly.
Keep in mind that no two documentations will ever be the same if they don’t follow any standardised practice. This can lead to some mess, making it hard to fetch the right information.
How exactly do we classify something as messy? When most of the documentation pieces don’t follow standard practices, it leads to inconsistency and hence a big mess! So how do you declutter messy open source documents?
**Decluttering messy open source documentation**
It is important to follow a ‘documentation style guide’. A style guide is a collection of guidelines for creating and presenting content. Whether you’re a standalone writer or part of a large documents team, it helps to keep a consistent style, voice and tone throughout your documentation.
There are several popular style guides available, such as the Red Hat style guide, Google documentation style guide, and Apple style guide. To choose one, first start by defining your requirements. If your requirements do not differ much from other open source projects, you can follow a readily-available style guide, or adapt the same style guide for your own purpose with a few changes here and there. Most of the grammar-related guidelines and content rules may be the same, but overall terminology can vary.
You will also be required to automate the adoption of these style guides within your projects. For this, you can use Vale, which is integrated into the local machinery with a continuous integration (CI) service that will help you to ensure your documentation follows the style guide in a strict manner.
*Reference guides:* These might include some basic references to get started with or some docs to contribute to the project.
*User facing documentation:* This is the most essential part that documents the usability of the project. Without any user-facing documentation most people will be lost as to how to go about working with the project.
*Developers’ documentation:* This aims to support development teams as they continuously make new progress in the project. It should also provide a good pathway to internal development efforts and make sure that the features are communicated well to the stakeholders.
*Community content:* This includes essential blogs, videos and external content that aim to support community members who would like to refer to the same for a better understanding of the project.
By using the style guide, the overall premise of the documentation will be conveyed to the users in a single tone. But since these documents are prepared by a team of technical writers, there can be conflicting writing styles, as these vary from person to person. So how do you standardise the documentation?
**Standardising documentation**
There are many approaches that can be taken when it comes to standardising documentation. The first one is obviously to create predefined templates which can be used for a variety of roles. These can be used for documenting new features, identifying bugs and issues, and updating the change log to accommodate new stuff that is being added.
Try to develop a standard workflow for publishing your documentation if you are following a Git based workflow. The most standard workflow will be to fork the repo where the documentation is published, add your changes on a local branch, push these changes, make your request and ask for reviews on the same. A positive that comes out of standardising your documents is a better feedback and review process.
**Feedback and automated reviews**
Standardisation allows you to get users’ feedback and generate automated reviews, which can be taken into consideration for improving the project and the documentation. With this feedback, you can also evaluate whether the information being shared is making sense to users or not. Having a proper feedback service in place through documentation platforms like GitBook helps to verify if the documentation is useful or not.
Always try to seek out subject matter expert (SME) feedback on the documentation. These SMEs can be stakeholders, developers, engineers, or even external contributors. You can also use automated tests and CI to verify if your documentation is following a style guide or not.
**Crowdsourced documentation efforts**
If you are looking to open source your documentation, perhaps the best way to get started is to provide a quick start guide. The guide can be as simple as ‘CONTRIBUTING.md’; basically, a file showing how a person can set up the project and contribute to or use it.
Always try to develop user-centric documentation that signifies the purpose of each project and build learning courses to help new contributors.
* What is the goal of this documentation?
* What is the message that needs to be given?
* What action would you like the user to take up after this?
* What are the values that I share with the reader?
* Am I concise and consistent in my writing efforts?
Defining a consistent content strategyA consistent content strategy helps to ensure a long-term vision for the documentation efforts and the project infrastructure. This can revolve around two main things:
a.* Resources:* Project docs, case studies and whitepapers, project architecture
b. *Branded content:* Blogs and guest posts, news and community stories, learning courses
Every open source project should have proper documentation stating the functionality it can provide to users, so that they can opt for the most suitable solution. Proper documentation that communicates the right information also allows other developers to put in their efforts to further enhance and improve the project. Simple though it sounds, documentation can only succeed if done right. And your project, in turn, can only succeed if your documentation is right, so never underestimate its purpose or process!
Curated By: Laveesh Kocher
--------------------------------------------------------------------------------
via: https://www.opensourceforu.com/2022/04/documentation-isnt-just-another-aspect-of-open-source-development/
作者：[Harsh Bardhan Mishra][a]
选题：[lkxed][b]
译者：[译者ID](https://github.com/译者ID)
校对：[校对者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

104
translated/talk/20220422 Documentation Isn’t Just Another Aspect of Open Source Development.md Normal file
View File

@ -0,0 +1,104 @@
[#]: 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