document/TranslateProject
2
0
Fork 0
mirror of https://github.com/LCTT/TranslateProject.git synced 2024-12-23 21:20:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #28259 from CanYellow/ThirdTrans

Browse Source 
finished Third trans
This commit is contained in:
Xingyu.Wang 2022-12-17 18:57:15 +08:00 committed by GitHub
commit d16e5e2c3c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 86 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
sources/talk/20221028.1 ⭐️⭐️ Write documentation like you develop code.md
View File

@ -1,85 +0,0 @@
[#]: subject: "Write documentation like you develop code"
[#]: via: "https://opensource.com/article/22/10/docs-as-code"
[#]: author: "Lorna Mitchell https://opensource.com/users/lornajane"
[#]: collector: "lkxed"
[#]: translator: "CanYellow"
[#]: reviewer: " "
[#]: publisher: " "
[#]: url: " "
Write documentation like you develop code
======
Don't want documentation to be an afterthought? Try a new approach.
Many engineers and craftspeople are particular about their tools. To do a job well, you need the best tools and the skills to use them. The best tools in software development can be very powerful when applied to other kinds of digital creation. The [Docs as Code][1] approach is a great example. Docs as Code entails writing documentation using the same tools and workflows used for developing code. Proponents of Docs as Code report that this method leads to better documentation while easing the workload of the people who write it.
### Text formats and source control
The most significant adjustment when moving from a more traditional documentation platform to the Docs as Code approach is that the content is stored in a text-based markup format. This change makes all the tools for text-based materials available for generating documentation. Whether you choose [DocBook][2], [Markdown][3], or another markup language, the transition from using just one tool to using a standard format and a variety of tools is a big change.
Finding tools that support your workflow is really important. Many developers use their [coding editors][4] when working on Docs as Code projects. Since they are already advanced-level users with that tool, it works well for them. Finding tooling that fits the other professionals on the team, such as technical writers, editors, information architects, and documentation product owners, may take more effort. A few options to consider:
- One of the many [good markdown editors][5] available
- Coding editors with good preview tools, which make them approachable for non-coders
- The web interfaces of popular Git hosting services, especially for occasional contributors
Once content is safely in a markup format, the project can use source control such as [Git][6], an open source tool with many more features than most documentation platforms can claim:
- A clear and detailed version history of who changed what and when. If you have good commit message culture, you may even be able to learn why the change was made.
- Easy parallel change processes. Working in branches in Git means everyone can make all the changes they want to and combine them at the end.
- Advanced collaboration and review tooling. All the source-control platforms are designed to review each change in detail and have as much discussion as needed until everyone is confident that the change can go ahead.
- Automated quality checks such as spellchecking and link checking. This saves time and catches errors that might otherwise be missed.
Source control has many benefits. Just keep in mind that if you're new to source control, it has a learning curve. There are some excellent [learning resources][7] and [articles for writers][8] that can help. You can also let your curious documentarians find the learning materials that work for them rather than asking your engineers to teach them. (Ask me how I learned this—the hard way of course!)
### Pull requests and review cycles
All source-control platforms are designed around the concept of pull requests, sometimes also called merge requests. Someone, or some team, puts together a set of changes and then requests that the changes are pulled into the main project. In many ways, working with many changes at once is easier in documentation than in code. Changing one article in one place in documentation has fewer side effects than when you change code and find that there were several other sections depending on it.
The most powerful collaboration tool is the [diff][9], which shows the difference between old and new versions in a way that's easy to follow. There are many versions of this tool available to make the comparison view easier to look at: side-by-side, inline, or even as rendered markdown rather than just text. Each team member can use the tool or tools that work best for them. For example, the web view is commonly used to look at a small change, but for something bigger I would want to look at it locally using `vimdiff` or [Meld][10].
Review comments can be added to the change as a whole or to individual lines in the proposed change. Some projects adopt a maximum line length, called a hard wrap, or start each sentence on a new line to make it easier to attach comments to specific parts of a block of text. Further changes and comments can be added until the review process is complete and the change is accepted. Since the pull requests are shown in a queue on the repository for the project, this is a good way to show what's in progress and what needs review attention. The tools make it easy for reviewers to add their thoughts. In particular, if you are working with technical audiences it can be easier to get reviews from these folks via the tools they use daily.
### Continuous integration and deployment
Having the source of your documentation available in plain text has many benefits, such as making it easy to find every occurrence of something that needs changing and using existing tools such as [wc][11], [grep][12], or `tree` to work with potentially large document sets. When you combine this with a source-control platform, even more existing tools become available, and they're all open source.
One big workflow improvement is the ability to have continuous deployment in place. This simply means that when a pull request is merged into the main project, the project is immediately and automatically deployed. If the change is good enough to be accepted into the project, it is also good enough to be live on the documentation site, helping your readers. Typically, continuous deployment is set up with either a separate automation server, such as [Jenkins][13], or [Git Hooks][14]. Either way, the text-based markup is combined with the Docs as Code platform (usually a static site generator such as [Hugo][15] or [Sphinx][16]) to produce the documentation website, which is then deployed.
The same automation can be used before deployment to add some excellent checks to the pull requests before they are merged. On a coding project, it's common to run code linters, tests, and other quality checks that a machine can do itself. Documentation projects can get the same treatment, with tools like [Vale][17] to do prose linting and check for correct heading styles, spellings, and so on. It's also useful to add other tools here, such as a link checker to make sure all the links go somewhere valid.
### Code tools for docs workflows
The tools known and loved by engineers are very good tools, but they are useful for all sorts of other projects too. For documentation, they contribute valuable efficiency, especially when you need your documentation to be moving at the same speed as your development teams. All the tools discussed here are open source, so you can try them for yourself, deploy them for a huge global team, or anything in between. May your docs process be as smooth as any code process.
--------------------------------------------------------------------------------
via: https://opensource.com/article/22/10/docs-as-code
作者：[Lorna Mitchell][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://opensource.com/users/lornajane
[b]: https://github.com/lkxed
[1]: https://www.writethedocs.org/guide/docs-as-code
[2]: https://opensource.com/article/17/9/docbook
[3]: http://commonmark.org
[4]: https://opensource.com/article/20/12/eclipse
[5]: https://opensource.com/article/21/10/markdown-editors
[6]: https://opensource.com/downloads/cheat-sheet-git
[7]: https://opensource.com/article/18/1/step-step-guide-git
[8]: https://opensource.com/article/19/4/write-git
[9]: https://opensource.com/article/21/11/linux-diff-patch
[10]: https://opensource.com/article/20/3/meld
[11]: https://www.redhat.com/sysadmin/linux-wc-command?intcmp=7013a000002qLH8AAM
[12]: https://opensource.com/downloads/grep-cheat-sheet
[13]: https://www.jenkins.io
[14]: https://www.redhat.com/sysadmin/git-hooks
[15]: https://opensource.com/article/18/3/start-blog-30-minutes-hugo
[16]: https://opensource.com/article/19/11/document-python-sphinx
[17]: https://vale.sh

86
translated/talk/20221028.1 ⭐️⭐️ Write documentation like you develop code.md Normal file
View File

@ -0,0 +1,86 @@
[#]: subject: "Write documentation like you develop code"
[#]: via: "https://opensource.com/article/22/10/docs-as-code"
[#]: author: "Lorna Mitchell https://opensource.com/users/lornajane"
[#]: collector: "lkxed"
[#]: translator: "CanYellow"
[#]: reviewer: " "
[#]: publisher: " "
[#]: url: " "
像代码开发一样撰写文档
======
不想让书写滞后于你的思考？或许你该尝试一下全新的写作方式。
很多工程师与手工艺者都对他们使用的工具有特别的要求。为了顺利的完成工作，你需要最好的工具和使用它们的技巧。软件开发中最好的工具在应用到其他的数字创作领域中也可以是很强大的。[Docs as Code][1] (译注：代码化文档)的方式就是很好的例子。Doc as Code 意味者使用与代码开发相同的工具与工作流来撰写文档。Doc as Code 的支持者认为这样的方式可以在降低作者的工作符负荷的同时保证更好的文档结构。
### 文本格式与源文件控制
从传统的写作平台切换到 Docs as Code 方式时，最主要的调整是写作内容保存在基于文本的标记格式中。这一转变使得基于纯文本材料的工具都适用于文档写作。当你选择 [DocBook][2]， [Markdown][3] 或者其他的标记语言时，从只使用一种工具到使用一种标准格式配合多种工具是一种巨大的转变。
找到支持你的工作流程的工具是非常重要的。在 Docs as Code 项目中，很多开发者使用他们的 [代码编辑器][4]。考虑到他们已经是这些工具的高阶用户，一切都很顺利。而找到适合团队里适合其他专业从业者，比如技术撰稿、编辑、信息架构师和文档产品责任人，的工具可能需要一番努力。这里有一些选项可兹参考：
- 各种[优秀的 Markdown 编辑器][5]之一是可行的
- 附带良好的预览工具的代码编辑器可能更适合非程序员
- 流行的 Git 托管服务的网页界面尤其适用于偶尔有需要的贡献者
一旦内容以标记语言的格式安全保存就可以使用版本控制进行管理，比如 [Git][6]。Git 相比大多数文档平台具有更多的功能：
- 清晰详细的文档版本历史：谁在什么时候改变了什么。
- 简明的并行修改过程支持。在 Git 中使用分支工作意味着任何人可以做出他们想要的任何改变并在最后合并所做的更改。
- 高级的协作与审查工具。所有的源代码管理平台都设计支持评审每一条细节变更并在足够的讨论后使每个人都确信改变可以继续的流程。
- 自动质量检查，比如拼写检查和链接检查。这不仅节省了时间，而且可以发现以前无法发现的错误。
源代码管理有很多优点。但要记住，如果你准备入门源代码管理，它有一定的学习曲线。这是一些有助于入门的优秀的[学习资源][7]和[作者文章][8]。你也可以让具有好奇心的文档作者自行寻找对他们有用的学习材料，而不是请你的工程师来培训他们。(探寻他人的学习历程是最困难的学习方式)
### 拉取请求和评审循环
所有的源代码管理平台都围绕拉取请求这一概念设计，这有时也称为合并请求。有时候，某些团队先将一系列改变整合到一起然后向主项目发起要求修改被拉取的请求。不过从许多方面来说，在文档中一次处理多个变更比在代码中更容易。改变文档中某处的一篇文章比之更改代码并找出有哪些地方依赖它具有更小的副作用。
最强大的协作工具是 [diff][9]，它可以通过一个易于察觉的方式展示旧版本与新版本之间的差异。该工具有多种不同的版本来使得比较视图更易于查看：双栏模式、行内模式，甚至是渲染后的 Markdown 模式。团队中的每一个成员都可以选择最适合他们的版本。举例而言，网页视图通常用于查看细微变更，而对于更大的变更，我习惯于使用 `vimdiff` 或 [Meld][10] 在本地浏览。
检查的注释可以整体提交到变更中，也可以提交到指定变更中的个别行中。一些项目限制了行的最大长度，即硬换行，或者一行一句，以使得向文本的特定的部分添加注释更加容易。进一步的变更与注释可以在检查完成接受变更时添加。由于拉取请求在项目仓库以队列形式展示，这是很好的方式来展示目前正在进行的任务以及需要进行检查操作的任务。diff 工具使得评审人员更方便地加入他们的思考。尤其是你在与技术受众工作时，你可以通过他们日常使用的工具获得来自他们的评论。
### 持续集成与部署
以纯文本形式拥有你的文档的源代码有很多益处，你可以轻易找到每次需要修改的位置，你可以使用现有的诸如 [wc][11]、[grep][12]或 `tree` 之类的工具在潜在的大型文档集中工作。当你将这些与源代码管理平台结合起来之后，你可能获得更多的可用工具，并且它们都是开源的。
另一个工作流程上的巨大提升是持续部署的能力。简单来说，这意味着，每当一个拉取请求被合并到主项目中，项目可以直接自动化部署到位。如果变更好到足以接收进项目中，他同时可以在文档页面中实时更新，从而帮助到你的读者。典型情况下，持续部署是配置在任意一台分离的自动化服务器上的，比如 [Jenkins][13] 或者 [Git Hooks][14]。不论哪种方式，基于文本的标记语言与 Doc as Code 平台(通常是静态网页生成器，比如 [Hugo][15] 或 [Sphinx][16])结合来生成文档网站，然后自动部署。
在部署之前，同样的自动化流程可以被用于对将要合并的拉取请求进行检查。在一个编程项目中，通过计算机自行进行代码检查、代码测试和其他的质量检查已经习以为常。通过类似 [Vale][17] 之类的工具进行文本检查、文档项目也可以同样对待，你也可以添加其他的工具，比如添加一个链接检查器来确保文中所有的链接都是有效的。
### 用于文档流程的代码工具
被工程师们熟知并喜爱的工具都是非常好的工具，它们同时也可以用于其他类型的项目中。在文档项目中，它们提升了宝贵的效率，尤其是当你希望你的文档与你的团队同步推进的时候。上面讨论到的所有工具都是开源的，你可以亲自尝试，为大型全球团队部署他们，亦或者介于两者之间，最终使你的成文过程和编程过程一样顺畅。
--------------------------------------------------------------------------------
via: https://opensource.com/article/22/10/docs-as-code
作者：[Lorna Mitchell][a]
选题：[lkxed][b]
译者：[CanYellow](https://github.com/CanYellow)
校对：[校对者ID](https://github.com/校对者ID)
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
[a]: https://opensource.com/users/lornajane
[b]: https://github.com/lkxed
[1]: https://www.writethedocs.org/guide/docs-as-code
[2]: https://opensource.com/article/17/9/docbook
[3]: http://commonmark.org
[4]: https://opensource.com/article/20/12/eclipse
[5]: https://opensource.com/article/21/10/markdown-editors
[6]: https://opensource.com/downloads/cheat-sheet-git
[7]: https://opensource.com/article/18/1/step-step-guide-git
[8]: https://opensource.com/article/19/4/write-git
[9]: https://opensource.com/article/21/11/linux-diff-patch
[10]: https://opensource.com/article/20/3/meld
[11]: https://www.redhat.com/sysadmin/linux-wc-command?intcmp=7013a000002qLH8AAM
[12]: https://opensource.com/downloads/grep-cheat-sheet
[13]: https://www.jenkins.io
[14]: https://www.redhat.com/sysadmin/git-hooks
[15]: https://opensource.com/article/18/3/start-blog-30-minutes-hugo
[16]: https://opensource.com/article/19/11/document-python-sphinx
[17]: https://vale.sh