mirror of
https://github.com/LCTT/TranslateProject.git
synced 2025-03-27 02:30:10 +08:00
Merge remote-tracking branch 'LCTT/master'
This commit is contained in:
Xingyu Wang
commit
c9baccb422
@ -1,69 +1,52 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (mengxinayan)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: reviewer: (wxy)
|
||||
[#]: publisher: (wxy)
|
||||
[#]: url: (https://linux.cn/article-12053-1.html)
|
||||
[#]: subject: (Basic Vim Commands You Need to Know to Work in Vim Editor)
|
||||
[#]: via: (https://www.2daygeek.com/basic-vim-commands-cheat-sheet-quick-start-guide/)
|
||||
[#]: author: (Magesh Maruthamuthu https://www.2daygeek.com/author/magesh/)
|
||||
|
||||
你需要知道的 Vim 编辑器中的基础命令
|
||||
必知必会的 Vim 编辑器基础命令
|
||||
======
|
||||
|
||||
如果你是一名系统管理员或者开发者，当你在终端工作时有时会需要编辑一个文件。
|
||||
|
||||
在 Linux 系统中有几种文件编辑器，你可以根据需求选择合适的文件编辑器
|
||||
|
||||
在这里，我想推荐 Vim 编辑器
|
||||
|
||||
如果你是一名系统管理员或者开发者，当你在终端工作时有时会需要编辑一个文件。在 Linux 系统中有几种文件编辑器，你可以根据需求选择合适的文件编辑器。在这里，我想推荐 Vim 编辑器。
|
||||
|
||||
### 为什么推荐 Vim 编辑器
|
||||
|
||||
和创建编写新文件相比，你会在编辑器中花费更多的时间用来修改已经存在的文件。
|
||||
相对于创建新文件，你更多是修改已经存在的文件。在这种情况下，Vim 快捷键可以有效地满足你的需求。
|
||||
|
||||
在这种情况下，Vim 快捷键可以有效地满足你的需求。
|
||||
|
||||
文章下面的内容可以帮助你了解对文件和目录的操作。
|
||||
|
||||
[Linux 基础：对文件和目录进行操作的 Linux 和 Unix 命令][1]
|
||||
[在 Linux 中查看不同文件格式的10种方法][2]
|
||||
下列文章可以帮助你了解对文件和目录的操作。
|
||||
|
||||
- [Linux 基础：对文件和目录进行操作的 Linux 和 Unix 命令][1]
|
||||
- [在 Linux 中查看不同文件格式的 10 种方法][2]
|
||||
|
||||
### 什么是 Vim
|
||||
|
||||
Vim 是被 Linux 管理员和开发者广泛使用的最流行和功能强大的编辑器之一。
|
||||
|
||||
它可以通过高度的自定义配置来提高文本编辑效率。它是在众多 Unix 默认安装的 Vi 编辑器的升级版。
|
||||
|
||||
Vim 通常被称为“程序员的编辑器”，但并不限于此，它也可用于编辑任何类型的文件。
|
||||
|
||||
它具有许多功能，例如：多次撤销，多窗口和缓冲区，语法高亮，命令行编辑，文件名补全，可视选择。
|
||||
|
||||
你可以使用 `:help` 命令来获取在线帮助
|
||||
Vim 是被 Linux 管理员和开发者广泛使用的最流行和功能强大的编辑器之一。它可以通过高度的自定义配置来提高文本编辑效率。它是在众多 Unix 默认安装的 Vi 编辑器的升级版。
|
||||
|
||||
Vim 通常被称为“程序员的编辑器”，但并不限于此，它也可用于编辑任何类型的文件。它具有许多功能，例如：多次撤销、多窗口和缓冲区、语法高亮、命令行编辑、文件名补全、可视选择等等。你可以使用 `:help` 命令来获取在线帮助。
|
||||
|
||||
### 理解 Vim 的模式
|
||||
|
||||
Vim 有两种模式，详细介绍如下：
|
||||
|
||||
**命令模式：** 当启动 Vim 编辑器后，默认处在命令模式下。你可以在文件中移动并且修改内容，剪切，复制和粘贴文件的一部分，同时发出命令执行更多操作（按 ESC 键进入命令模式）
|
||||
**命令模式：** 当启动 Vim 编辑器后，默认处在命令模式下。你可以在文件中移动并且修改内容，剪切、复制和粘贴文件的一部分，同时发出命令执行更多操作（按 `ESC` 键进入命令模式）
|
||||
|
||||
**插入模式：** 插入模式用于在给定的文档位置插入文本（按 i 键进入插入模式）
|
||||
**插入模式：** 插入模式用于在给定的文档位置插入文本（按 `i` 键进入插入模式）
|
||||
|
||||
### 我如何知道我正使用哪种 Vim 模式呢？
|
||||
|
||||
如果你正在使用插入模式，你会在编辑器的底部看到 `INSERT` 。如果编辑器底部没有显示任何内容，或者在编辑器底部显示了文件名，则处于 “命令模式”。
|
||||
如果你正在使用插入模式，你会在编辑器的底部看到 `INSERT`。如果编辑器底部没有显示任何内容，或者在编辑器底部显示了文件名，则处于 “命令模式”。
|
||||
|
||||
### 正常模式下的光标移动
|
||||
### Cursor Movement in Normal Mode
|
||||
### 命令模式下的光标移动
|
||||
|
||||
Vim 快捷键允许你使用不同的方式来移动光标：
|
||||
|
||||
* `G` – 跳转到文件最后一行
|
||||
* `gg` – 跳转到文件首行
|
||||
* `$` – 跳转到行末尾
|
||||
* `0` (零) – 跳转到行开头
|
||||
|
||||
* `0`（数字 0） – 跳转到行开头
|
||||
* `w` – 跳转到下一个单词的开始（单词的分隔符可以是空格或其他符号）
|
||||
* `W` – 跳转到下一个单词的开始（单词的分隔符只能是空格）
|
||||
* `b` – 跳转到下一个单词的末尾（单词的分隔符可以是空格或其他符号）
|
||||
@ -74,10 +57,9 @@ Vim 快捷键允许你使用不同的方式来移动光标：
|
||||
* `Ctrl+d` – 向下移动半页
|
||||
* `Ctrl+u` – 向上移动半页
|
||||
|
||||
|
||||
### 插入模式：插入文字
|
||||
|
||||
下面的 vim 快捷键允许你根据需要在光标的不同位置插入内容。
|
||||
下面的 Vim 快捷键允许你根据需要在光标的不同位置插入内容。
|
||||
|
||||
* `i` – 在光标之前插入
|
||||
* `a` – 在光标之后插入
|
||||
@ -87,26 +69,22 @@ Vim 快捷键允许你使用不同的方式来移动光标：
|
||||
* `O` – 在光标所在行的上面插入新行
|
||||
* `ea` – 在单词的末尾插入
|
||||
|
||||
|
||||
### 拷贝，粘贴和删除一行
|
||||
### 拷贝、粘贴和删除一行
|
||||
|
||||
* `yy` – 复制一行
|
||||
* `p/P` – 将内容粘贴到光标之后 / 将内容粘贴到光标之前
|
||||
* `p` / `P` – 将内容粘贴到光标之后 / 之前
|
||||
* `dd` – 删除一行
|
||||
* `dw` – 删除一个单词
|
||||
|
||||
### 在 Vim 中搜索和替换匹配的模式
|
||||
|
||||
### 在 Vim 中搜索和替换模式
|
||||
|
||||
* `/pattern` – 向后搜索给定的模式
|
||||
* `?pattern` – 向前搜索给定的模式
|
||||
* `/模式` – 向后搜索给定的模式
|
||||
* `?模式` – 向前搜索给定的模式
|
||||
* `n` – 向后重复搜索之前给定的模式
|
||||
* `N` – 向前重复搜索之前给定的模式
|
||||
|
||||
* `:%s/old-pattern/new-pattern/g` – 将文件中所有的旧模式替换为新模式
|
||||
* `:s/old-pattern/new-pattern/g` – 将当前行中所有的旧模式替换为新模式
|
||||
* `:%s/old-pattern/new-pattern/gc` – 逐个询问是否文件中的旧模式替换为新模式
|
||||
|
||||
* `:%s/旧模式/新模式/g` – 将文件中所有的旧模式替换为新模式
|
||||
* `:s/旧模式/新模式/g` – 将当前行中所有的旧模式替换为新模式
|
||||
* `:%s/旧模式/新模式/gc` – 逐个询问是否文件中的旧模式替换为新模式
|
||||
|
||||
### 如何在 Vim 编辑器中跳转到特定行
|
||||
|
||||
@ -127,7 +105,7 @@ Vim 快捷键允许你使用不同的方式来移动光标：
|
||||
如果你已经知道行号，请使用以下方法在打开文件时直接跳转到相应行。例如，如果在打开文件时直接跳转到 20 行，请输入下面的命令：
|
||||
|
||||
```
|
||||
$ vim +20 [File_Name]
|
||||
$ vim +20 [文件名]
|
||||
```
|
||||
|
||||
### 撤销操作/恢复上一次操作/重复上一次操作
|
||||
@ -136,14 +114,12 @@ $ vim +20 [File_Name]
|
||||
* `Ctrl+r` – 恢复更改
|
||||
* `.` – 重复上一条命令
|
||||
|
||||
|
||||
### 保存和退出 Vim
|
||||
|
||||
* `:w` – 保存更改但不退出 vim
|
||||
* `:wq` – 写并退出
|
||||
* `:q!` – 强制退出
|
||||
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://www.2daygeek.com/basic-vim-commands-cheat-sheet-quick-start-guide/
|
||||
@ -151,7 +127,7 @@ via: https://www.2daygeek.com/basic-vim-commands-cheat-sheet-quick-start-guide/
|
||||
作者：[Magesh Maruthamuthu][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[萌新阿岩](https://github.com/mengxinayan)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
校对：[wxy](https://github.com/wxy)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
@ -0,0 +1,104 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (HankChow)
|
||||
[#]: reviewer: (wxy)
|
||||
[#]: publisher: (wxy)
|
||||
[#]: url: (https://linux.cn/article-12052-1.html)
|
||||
[#]: subject: (How to write effective documentation for your open source project)
|
||||
[#]: via: (https://opensource.com/article/20/3/documentation)
|
||||
[#]: author: (Kevin Xu https://opensource.com/users/kevin-xu)
|
||||
|
||||
如何为你的开源项目编写实用的文档
|
||||
======
|
||||
|
||||
> 一份优质的文档可以让很多用户对你的项目路人转粉。
|
||||
|
||||
|
||||
|
||||
好的代码很多时候并不代表一切。或许你能用最精巧的代码解决了世界上最迫切需要解决的问题，但如果你作为一个开源开发者，没能用准确的语言将你的作品公之于世，你的代码也只能成为沧海遗珠。因此，技术写作和文档编写是很重要的技能。
|
||||
|
||||
一般来说，项目中的文档是最受人关注的部分，很多用户会通过文档来决定自己是否应该对某个项目开始学习或研究。所以，我们不能忽视技术写作和文档编写的工作，尤其要重点关注其中的“<ruby>入门<rt>Getting Started</rt></ruby>”部分，这会对你项目的发展起到关键性的作用。
|
||||
|
||||
对于很多人来说，写作是一件令人厌烦甚至恐惧的事情。我们这些工程师出身的人，更多学习的是“写代码”而不是学习“为代码写文档”。不少人会把英语作为自己的第二语言或者第三语言，他们可能会对英语写作感到不自信甚至害怕（我的母语是汉语，英语是作为我的第二语言学习的，所以我也能感受到这种痛苦）。
|
||||
|
||||
但如果你希望自己的项目能在全球范围内产生一定的影响力，英语就是你必须使用的语言，这是一个无法避免的现实。但不必害怕，我在写这篇文章的时候就考虑到了这些可能带来的挑战，并给出了我的一些建议。
|
||||
|
||||
### 五条有用的写作建议
|
||||
|
||||
这五条建议你马上就可以用起来，尽管看起来似乎有些浅显，但在技术写作时却经常被忽视。
|
||||
|
||||
1. **使用主动语态**：感受一下[主动语态][2]下的“你可以这样更改配置（You can change these configurations by...）”和被动语态下的“配置可以这样更改（These configurations can be changed by…）”有什么不同之处。
|
||||
2. **使用简洁明了的句子**：可以借助 [Hemingway App][3] 或者 [Grammarly][4] 这样的工具，尽管它们并不开源。
|
||||
3. **保持条理性**：你可以在文档中通过写标题、划重点、引链接等方式，把各类信息划分为不同的部分，避免将所有内容都杂糅在一大段冗长的文字当中。
|
||||
4. **提高可读性**：除了单纯的文字之外，运用图表也是从多种角度表达的手段之一。
|
||||
5. **注意拼写和语法**：必须记得检查文档中是否有拼写错误或者语法错误。
|
||||
|
||||
只要在文档的写作和编辑过程中应用到这些技巧，你就能够和读者建立起沟通和信任。
|
||||
|
||||
* **高效沟通**：对于工程师们来说，阅读长篇大论的冗长文字，还不如去看小说。在阅读技术文档时，他们总是希望能够从中快速准确地获取到有用的信息。因此，技术文档的最佳风格应该是精简而有效的，不过这并不代表文档中不能出现类似幽默、emoji 甚至段子这些东西，这些元素可以当你的文档更有个性、更使人印象深刻。当然，具体的实现方式就因人而异了
|
||||
* **建立信任**：你需要取得文档读者们的信任，这在一个项目的前期尤为重要。读者对你的信任除了来源于你代码的质量，还跟你文档编写的质量有关。所以你不仅要打磨代码，还要润色好相关的文档，这也是上面第 5 点建议拼写和语法检查的原因。
|
||||
|
||||
### 从编写“入门”文档开始
|
||||
|
||||
现在，最需要花费功夫的应该就是“入门”部分了，这是一篇技术文档最重要的部分，[二八定律][5]在这里得到了充分体现：访问一个项目的大部分流量都会落在项目文档上，而访问项目文档的大部分流量则会落在文档的“入门”部分中。因此，如果文档的“入门”部分写得足够好，项目就会吸引到很多用户，反之，用户会对你的项目敬而远之。
|
||||
|
||||
那么如何写好“入门”部分呢？我建议按照以下三步走：
|
||||
|
||||
1. **任务化**：入门指南应该以任务为导向。这里的任务指的是对于开发者来说可以完成的离散的小项目，而不应该包含太多涉及到体系结构、核心概念等的抽象信息，因此在“入门”部分只需要提供一个简单明了的概述就可以了。也不要在“入门”部分大谈这个项目如何优秀地解决了问题，这个话题可以放在文档中别的部分进行说明。总而言之，“入门”部分最好是给出一些主要的操作步骤，这样显得开门见山。
|
||||
2. **30 分钟内能够完成**：这一点的核心是耗时尽可能短，不宜超过 30 分钟，这个时间上限是考虑到用户可能对你的项目并不了解。这一点很重要，大部分愿意浏览文档的人都是有技术基础的，但对你的项目也仅仅是一知半解。首先让这些读者尝试进行一些相关操作，在收到一定效果后，他们才会愿意花更多时间深入研究整个项目。因此，你可以从耗时这个角度来评估你的文档“入门”部分有没有需要改进之处。
|
||||
3. **有意义的任务**：这里“有意义”的含义取决于你的开源项目。最重要的是认真思考并将“入门”部分严格定义为一项任务，然后交给你的读者去完成。这个项目的价值应该在这项有意义的任务中有所体现，不然读者可能会感觉这是一个浪费时间的行为。
|
||||
|
||||
提示：假如你的项目是一个分布式数据库，那么达到“整个集群在某些节点故障的情况下可以不中断地保持可用”的目标就可以认为是“有意义”的；假如你的项目是一个数据分析工具或者是商业智能工具，“有意义”的目标也可以是“加载数据后能快速生成多种可视化效果的仪表板”。总之，无论你的项目需要达到什么“有意义”的目标，都应该能在笔记本电脑上本地快速实现。
|
||||
|
||||
[Linkerd 入门][6]就是一个很好的例子。Linkerd 是一个开源的 Kubernetes <ruby>服务网格<rt>Service Mesh</rt></ruby>，当时我对 Kubernetes 了解并不多，也不熟悉服务网格。但我在自己的笔记本电脑上很轻松地就完成了其中的任务，同时也加深了对服务网格的理解。
|
||||
|
||||
上面提到的三步过程是一个很有用的框架，对一篇文档“入门”部分的设计和量化评估很有帮助。今后你如果想将你的[开源项目产品化][7]，这个框架还可能对<ruby>实现价值的时间<rt>time-to-value</rt></ruby>产生影响。
|
||||
|
||||
### 其它核心部分
|
||||
|
||||
认真写好“入门”部分之后，你的文档中还需要有这五个部分：架构设计、生产环境使用指导、使用案例、参考资料以及未来展望，这五个部分在一份完整的文档中是必不可少的。
|
||||
|
||||
* **架构设计**：这一部分需要深入探讨整个项目架构设计的依据，“入门”部分中那些一笔带过的关键细节就应该在这里体现。在产品化过程中，这个部分将会是[产品推广计划][8]的核心，因此通常会包含一些可视化呈现的内容，期望的效果是让更多用户长期参与到项目中来。
|
||||
* **生产环境使用指导**：对于同一个项目，在生产环境中部署比在笔记本电脑上部署要复杂得多。因此，指导用户认真使用就尤为重要。同时，有些用户可能对项目很感兴趣，但对生产环境下的使用有所顾虑，而指导和展示的过程则正好能够吸引到这类潜在的用户。
|
||||
* **使用案例**：<ruby>社会认同<rt>social proof</rt></ruby>的力量是有目共睹的，所以很有必要列出正在生产环境使用这个项目的其他用户，并把这些信息摆放在显眼的位置。这个部分的浏览量甚至仅次于“入门”部分。
|
||||
* **参考资料**：这个部分是对项目的一些详细说明，让用户得以进行详细的研究以及查阅相关信息。一些开源作者会在这个部分事无巨细地列出项目中的每一个细节和<ruby>边缘情况<rt>edge case</rt></ruby>，这种做法可以理解，但不推荐在项目初期就在这个部分花费过多的时间。你可以采取更折中的方式，在质量和效率之间取得平衡，例如提供一些相关社区的链接、Stack Overflow 上的标签或单独的 FAQ 页面。
|
||||
* **未来展望**：你需要制定一个简略的时间表，规划这个项目的未来发展方向，这会让用户长期保持兴趣。尽管项目在当下可能并不完美，但要让用户知道你仍然有完善这个项目的计划。这个部分也能让整个社区构建一个强大的生态，因此还要向用户提供表达他们对未来展望的看法的交流区。
|
||||
|
||||
以上这几个部分或许还没有在你的文档中出现，甚至可能会在后期才能出现，尤其是“使用案例”部分。尽管如此，还是应该在文档中逐渐加入这些部分。如果用户对“入门”部分已经感觉良好，那以上这几个部分将会提起用户更大的兴趣。
|
||||
|
||||
最后，请在“入门”部分、README 文件或其它显眼的位置注明整个项目所使用的许可证。这个细节会让你的项目更容易通过最终用户的审核。
|
||||
|
||||
### 花 20% 的时间写作
|
||||
|
||||
一般情况下，我建议把整个项目 10% 到 20% 的时间用在文档写作上。也就是说，如果你是全职进行某一个项目的，文档写作需要在其中占半天到一天。
|
||||
|
||||
再细致一点，应该将写作纳入到常规的工作流程中，这样它就不再是一件孤立的琐事，而是日常的事务。文档写作应该随着工作进度同步进行，切忌将所有写作任务都堆积起来最后完成，这样才可以帮助你的项目达到最终目标：吸引用户、获得信任。
|
||||
|
||||
* * *
|
||||
|
||||
*特别鸣谢云原生计算基金会的布道师 [Luc Perkins][9] 给出的宝贵意见。*
|
||||
|
||||
*本文首发于 [COSS Media][10] 并经许可发布。*
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/20/3/documentation
|
||||
|
||||
作者：[Kevin Xu][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[HankChow](https://github.com/HankChow)
|
||||
校对：[wxy](https://github.com/wxy)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/kevin-xu
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/osdc-docdish-typewriter-pink.png?itok=OXJBtyYf (A pink typewriter)
|
||||
[2]: https://www.grammar-monster.com/glossary/active_voice.htm
|
||||
[3]: http://www.hemingwayapp.com/
|
||||
[4]: https://www.grammarly.com/
|
||||
[5]: https://en.wikipedia.org/wiki/Pareto_principle
|
||||
[6]: https://linkerd.io/2/getting-started/
|
||||
[7]: https://opensource.com/article/19/11/products-open-source-projects
|
||||
[8]: https://opensource.com/article/20/2/product-marketing-open-source-project
|
||||
[9]: https://twitter.com/lucperkins
|
||||
[10]: https://coss.media/open-source-documentation-technical-writing-101/
|
||||
@ -1,131 +0,0 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (geekpi)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (Don't love diff? Use Meld instead)
|
||||
[#]: via: (https://opensource.com/article/20/3/meld)
|
||||
[#]: author: (Ben Nuttall https://opensource.com/users/bennuttall)
|
||||
|
||||
Don't love diff? Use Meld instead
|
||||
======
|
||||
Meld is a visual diff tool that makes it easier to compare and merge
|
||||
changes in files, directories, Git repos, and more.
|
||||
![Person drinking a hat drink at the computer][1]
|
||||
|
||||
Meld is one of my essential tools for working with code and data files. It's a graphical diff tool, so if you've ever used the **diff** command and struggled to make sense of the output, [Meld][2] is here to help.
|
||||
|
||||
Here is a brilliant description from the project's website:
|
||||
|
||||
> "Meld is a visual diff and merge tool targeted at developers. Meld helps you compare files, directories, and version controlled projects. It provides two- and three-way comparison of both files and directories, and has support for many popular version control systems.
|
||||
>
|
||||
> "Meld helps you review code changes and understand patches. It might even help you to figure out what is going on in that merge you keep avoiding."
|
||||
|
||||
You can install Meld on Debian/Ubuntu systems (including Raspbian) with:
|
||||
|
||||
|
||||
```
|
||||
`$ sudo apt install meld`
|
||||
```
|
||||
|
||||
On Fedora or similar, it's:
|
||||
|
||||
|
||||
```
|
||||
`$ sudo dnf install meld`
|
||||
```
|
||||
|
||||
Meld is cross-platform—there's a [Windows install][3] using the [Chocolately][4] package manager. While it's not officially supported on macOS, there are [builds available for Mac][5], and you can install it on Homebrew with:
|
||||
|
||||
|
||||
```
|
||||
`$ brew cask install meld`
|
||||
```
|
||||
|
||||
See Meld's homepage for [additional options][2].
|
||||
|
||||
### Meld vs. the diff command
|
||||
|
||||
If you have two similar files (perhaps one is a modified version of the other) and want to see the changes between them, you could run the **diff** command to see their differences in the terminal:
|
||||
|
||||
![diff output][6]
|
||||
|
||||
This example shows the differences between **conway1.py** and **conway2.py**. It's showing that I:
|
||||
|
||||
* Removed the [shebang][7] and second line
|
||||
* Removed **(object)** from the class declaration
|
||||
* Added a docstring to the class
|
||||
* Swapped the order of **alive** and **neighbours == 2** in a method
|
||||
|
||||
|
||||
|
||||
Here's the same example using the **meld** command. You can run the same comparison from the command line with:
|
||||
|
||||
|
||||
```
|
||||
`$ meld conway1.py conway2.py`
|
||||
```
|
||||
|
||||
![Meld output][8]
|
||||
|
||||
Much clearer!
|
||||
|
||||
You can easily see changes and merge changes between files by clicking the arrows (they work both ways). You can even edit the files live (Meld doubles up as a simple text editor with live comparisons as you type)—just be sure to save before you close the window.
|
||||
|
||||
You can even compare and edit three different files:
|
||||
|
||||
![Comparing three files in Meld][9]
|
||||
|
||||
### Meld's Git-awareness
|
||||
|
||||
Hopefully, you're using a version control system like [Git][10]. If so, your comparison isn't between two different files but to find differences between the current working file and the one Git knows. Meld understands this, so if you run **meld conway.py**, where **conway.py** is known by Git, it'll show you any changes made since the last Git commit:
|
||||
|
||||
![Comparing Git files in Meld][11]
|
||||
|
||||
You can see changes made in the current version (on the right) and the repository version (on the left). You can see I deleted a method and added a parameter and a loop since the last commit.
|
||||
|
||||
If you run **meld .**, you'll see all the changes in the current directory (or the whole repository, if you're in its root):
|
||||
|
||||
![Meld . output][12]
|
||||
|
||||
You can see a single file is modified, another file is unversioned (meaning it's new to Git, so I need to **git add** the file before comparing it), and lots of other unmodified files. Various display options are provided by icons along the top.
|
||||
|
||||
You can also compare two directories, which is sometimes handy:
|
||||
|
||||
![Comparing directories in Meld][13]
|
||||
|
||||
### Conclusion
|
||||
|
||||
Even regular users can find comparisons with diff difficult to decipher. I find the visualizations Meld provides make a big difference in troubleshooting what's changed between files. On top of that, Meld comes with some helpful awareness of version control and helps you compare across Git commits without thinking much about it. Give Meld a go, and make troubleshooting a little easier on the eyes.
|
||||
|
||||
* * *
|
||||
|
||||
_This was originally published on Ben Nuttall's [Tooling blog][14] and is reused with permission._
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/20/3/meld
|
||||
|
||||
作者：[Ben Nuttall][a]
|
||||
选题：[lujun9972][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/bennuttall
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/coffee_tea_laptop_computer_work_desk.png?itok=D5yMx_Dr (Person drinking a hat drink at the computer)
|
||||
[2]: https://meldmerge.org/
|
||||
[3]: https://chocolatey.org/packages/meld
|
||||
[4]: https://opensource.com/article/20/3/chocolatey
|
||||
[5]: https://yousseb.github.io/meld/
|
||||
[6]: https://opensource.com/sites/default/files/uploads/diff-output.png (diff output)
|
||||
[7]: https://en.wikipedia.org/wiki/Shebang_(Unix)
|
||||
[8]: https://opensource.com/sites/default/files/uploads/meld-output.png (Meld output)
|
||||
[9]: https://opensource.com/sites/default/files/uploads/meld-3-files.png (Comparing three files in Meld)
|
||||
[10]: https://opensource.com/resources/what-is-git
|
||||
[11]: https://opensource.com/sites/default/files/uploads/meld-git.png (Comparing Git files in Meld)
|
||||
[12]: https://opensource.com/sites/default/files/uploads/meld-directory-changes.png (Meld . output)
|
||||
[13]: https://opensource.com/sites/default/files/uploads/meld-directory-compare.png (Comparing directories in Meld)
|
||||
[14]: https://tooling.bennuttall.com/meld/
|
||||
@ -1,5 +1,5 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: ( )
|
||||
[#]: translator: (geekpi)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
|
||||
@ -1,106 +0,0 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (HankChow)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (How to write effective documentation for your open source project)
|
||||
[#]: via: (https://opensource.com/article/20/3/documentation)
|
||||
[#]: author: (Kevin Xu https://opensource.com/users/kevin-xu)
|
||||
|
||||
如何为你的开源项目编写实用的文档
|
||||
======
|
||||
一份优质的文档可以让很多用户对你的项目路人转粉。
|
||||
|
||||
![A pink typewriter][1]
|
||||
|
||||
好的代码很多时候并不代表一切。或许你能用最精巧的代码解决了世界上最迫切需要解决的问题，但如果你作为一个开源开发者，没能用准确的语言将你的作品公之于世，你的代码也只能成为沧海遗珠。因此，技术写作和文档编写是很重要的技能。
|
||||
|
||||
一般来说，项目中的文档是最受人关注的部分，很多用户会通过文档来决定自己是否应该对某个项目开始学习或研究。所以，我们不能忽视技术写作和文档编写的工作，尤其要重点关注其中的“入门”部分，这会对你项目的发展起到关键性的作用。
|
||||
|
||||
对于很多人来说，写作是一件令人厌烦甚至恐惧的事情。我们这些工程师出身的人，学习“写代码”比学习“为代码写文档”明显更多。不少人会把英语作为自己的第二语言或者第三语言，他们可能会对英语写作感到不安全甚至害怕（我的母语是汉语，英语是作为我的第二语言学习的，所以我也能感受到这种痛苦）。
|
||||
|
||||
但如果你希望自己的项目能在全球范围内产生一定的影响力，英语就是你必须使用的语言，这是一个无法避免的现实。但不必害怕，我在写这篇文章的时候就考虑到了这些可能带来的挑战，并给出了我的一些建议。
|
||||
|
||||
### 五条有用的写作建议
|
||||
|
||||
这五条建议你马上就可以用起来，尽管看起来似乎有些浅显，但在技术写作时却经常被忽视。
|
||||
|
||||
1. 使用[主动语态][2]：感受一下主动语态下的“你可以这样更改配置（You can change these configurations by…）”和被动语态下的“配置可以这样更改（These configurations can be changed by…）”有什么不同之处。
|
||||
2. 使用简洁明了的句子：可以借助 [Hemingway App][3] 或者 [Grammarly][4] 这样的工具，尽管它们并不开源。
|
||||
3. 保持条理性：你可以在文档中通过写标题、划重点、引链接等方式，把各类信息划分为不同的部分，避免将所有内容都杂糅在一大段冗长的文字当中。
|
||||
4. 提高可读性：除了单纯的文字之外，运用图表也是从多种角度表达的手段之一。
|
||||
5. 注意拼写和语法：必须记得检查文档中是否有拼写错误或者语法错误。
|
||||
|
||||
只要在文档的写作和编辑过程中应用到这些技巧，你就能够和读者建立起沟通和信任。
|
||||
|
||||
* 高效沟通：对于工程师们来说，阅读长篇大论的冗长文字，还不如去看小说。在阅读技术文档时，他们总是希望能够从中快速准确地获取到有用的信息。因此，技术文档的最佳风格应该是精简而有效的，不过这并不代表文档中不能出现类似幽默、emoji 甚至段子这些东西，这些元素可以当你的文档更有个性、更使人印象深刻。当然，具体的实现方式就因人而异了
|
||||
* 建立信任：你需要取得文档读者们的信任，这在一个项目的前期尤为重要。读者对你的信任除了来源于你代码的质量，还跟你文档编写的质量有关。所以你不仅要打磨代码，还要润色好相关的文档，这也是上面第 5 点建议拼写和语法检查的原因。
|
||||
|
||||
### 如何开始编写文档
|
||||
|
||||
现在，最需要花费功夫的应该就是“入门”部分了，这是一篇技术文档最重要的部分，[二八定律][5]在这里得到了充分体现：访问一个项目的大部分流量都会落在项目文档上，而访问项目文档的大部分流量则会落在文档的“入门”部分中。因此，如果文档的“入门”部分写得足够好，项目就会吸引到很多用户，反之，用户会对你的项目敬而远之。
|
||||
|
||||
那么如何写好“入门”部分呢？我建议按照以下三步走：
|
||||
|
||||
1. 任务化：入门指南应该以任务为导向。这里的任务指的是对于开发者来说可以完成的离散的小项目，而不应该包含太多涉及到体系结构、核心概念等的抽象信息，因此在“入门”部分只需要提供一个简单明了的概述就可以了。也不要在“入门”部分大谈这个项目如何优秀地解决了问题，这个话题可以放在文档中别的部分进行说明。总而言之，“入门”部分最好是给出一些主要的操作步骤，这样显得开门见山。
|
||||
2. 30 分钟内能够完成：这一点的核心是耗时尽可能短，不宜超过 30 分钟，这个时间上限是考虑到用户可能对你的项目并不了解。这一点很重要，大部分愿意浏览文档的人都是有技术基础的，但对你的项目也仅仅是一知半解。首先让这些读者尝试进行一些相关操作，在收到一定效果后，他们才会愿意花更多时间深入研究整个项目。因此，你可以从耗时这个角度来评估你的文档“入门”部分有没有需要改进之处。
|
||||
3. 有意义的任务：这里“有意义”的含义取决于你的开源项目。最重要的是认真思考并将“入门”部分严格定义为一项任务，然后交给你的读者去完成。这个项目的价值应该在这项有意义的任务中有所体现，不然读者可能会感觉这是一个浪费时间的行为。
|
||||
|
||||
提示：假如你的项目是一个分布式数据库，那么达到“整个集群在某些节点故障的情况下可以不中断地保持可用”的目标就可以认为是“有意义”的；加入你的项目是一个数据分析工具或者是商业智能工具，“有意义”的目标也可以是“加载数据后能快速生成多种可视化效果的仪表板”。总之，无论你的项目需要达到什么“有意义”的目标，都应该能在笔记本电脑上本地快速实现。
|
||||
|
||||
[Linkerd 入门][6]就是一个很好的例子。Linkerd 是 Kubernetes 的开源<ruby>服务网格<rt>Service Mesh</rt></ruby>，当时我对 Kubernetes 了解并不多，也不熟悉服务网格。但我在自己的笔记本电脑上很轻松地就完成了其中的任务，同时也加深了对服务网格的理解。
|
||||
|
||||
上面提到的三步过程是一个很有用的框架，对一篇文档“入门”部分的设计和量化评估很有帮助。今后你如果想将你的[开源项目产品化][7]，这个框架还可能对<ruby>实现价值的时间<rt>time-to-value</rt></ruby>产生影响。
|
||||
|
||||
### 其它核心部分
|
||||
|
||||
认真写好“入门”部分之后，你的文档中还需要有这五个部分：架构设计、生产环境使用指导、使用案例、参考资料以及未来展望，这五个部分在一份完整的文档中是必不可少的。
|
||||
|
||||
* 架构设计：这一部分需要深入探讨整个项目架构设计的依据，“入门”部分中一笔带过的那些关键细节就应该在这里体现。在产品化过程中，这个部分将会是[产品推广计划][8]的核心，因此通常会包含一些可视化呈现的内容，期望的效果是让更多用户长期参与到项目中来。
|
||||
* 生产环境使用指导：对于同一个项目，在生产环境中部署比在笔记本电脑上部署要复杂得多。因此，指导用户认真使用就尤为重要。同时，有些用户可能对项目很感兴趣，但对生产环境下的使用有所顾虑，而指导和展示的过程则正好能够吸引到这类潜在的用户。
|
||||
* 使用案例：<ruby>社会认同<rt>social proof</rt></ruby>的力量是有目共睹的，所以很有必要列出正在生产环境使用这个项目的其他用户，并把这些信息摆放在显眼的位置。这个部分的浏览量甚至仅次于“入门”部分。
|
||||
* 参考资料：这个部分是对项目的一些详细说明，让用户得以进行详细的研究以及查阅相关信息。一些开源作者会在这个部分事无巨细地列出项目中的每一个细节和<ruby>边缘情况<rt>edge case</rt></ruby>，这种做法可以理解，但不推荐在项目初期就在这个部分花费过多的时间。你可以采取更折中的方式，在质量和效率之间取得平衡，例如提供一些相关社区的链接、Stack Overflow 上的标签或单独的 FAQ 页面。
|
||||
* 未来展望：你需要制定一个简略的时间表，规划这个项目的未来发展方向，这会让用户长期保持兴趣。尽管项目在当下可能并不完美，但要让用户知道你仍然有完善这个项目的计划。这个部分也能让整个社区构建一个强大的生态，因此还要向用户提供表达他们对未来展望的看法的交流区。
|
||||
|
||||
以上这几个部分或许还没有在你的文档中出现，甚至可能会在后期才能出现，尤其是“使用案例”部分。尽管如此，还是应该在文档中逐渐加入这些部分。如果用户对“入门”部分已经感觉良好，那以上这几个部分将会提起用户更大的兴趣。
|
||||
|
||||
最后，请在“入门”部分、README 文件或其它显眼的位置注明整个项目所使用的许可证。这个细节会让你的项目更容易通过终端用户的审核。
|
||||
|
||||
### 花 20% 的时间写作
|
||||
|
||||
一般情况下，我建议把整个项目 10% 到 20% 的时间用在文档写作上。也就是说，如果你是全职进行某一个项目的，文档写作需要在其中占半天到一天。
|
||||
|
||||
再细致一点，应该将写作纳入到常规的工作流程中，这样它就不再是一件孤立的琐事，而是日常的事务。文档写作应该随着工作进度同步进行，切忌将所有写作任务都堆积起来最后完成，这样才可以帮助你的项目达到最终目标：吸引用户、获得信任。
|
||||
|
||||
* * *
|
||||
|
||||
_特别鸣谢云原生计算基金会的布道师 [Luc Perkins][9] 给出的宝贵意见。_
|
||||
|
||||
_本文首发于_ _[COSS Media][10]_ _并经许可发布。_
|
||||
|
||||
Nigel Babu 提供了 10 条帮助编写项目文档的有用技巧。
|
||||
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/20/3/documentation
|
||||
|
||||
作者：[Kevin Xu][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[HankChow](https://github.com/HankChow)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/kevin-xu
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/osdc-docdish-typewriter-pink.png?itok=OXJBtyYf (A pink typewriter)
|
||||
[2]: https://www.grammar-monster.com/glossary/active_voice.htm
|
||||
[3]: http://www.hemingwayapp.com/
|
||||
[4]: https://www.grammarly.com/
|
||||
[5]: https://en.wikipedia.org/wiki/Pareto_principle
|
||||
[6]: https://linkerd.io/2/getting-started/
|
||||
[7]: https://opensource.com/article/19/11/products-open-source-projects
|
||||
[8]: https://opensource.com/article/20/2/product-marketing-open-source-project
|
||||
[9]: https://twitter.com/lucperkins
|
||||
[10]: https://coss.media/open-source-documentation-technical-writing-101/
|
||||
129
translated/tech/20200323 Don-t love diff- Use Meld instead.md
Normal file
129
translated/tech/20200323 Don-t love diff- Use Meld instead.md
Normal file
@ -0,0 +1,129 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (geekpi)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (Don't love diff? Use Meld instead)
|
||||
[#]: via: (https://opensource.com/article/20/3/meld)
|
||||
[#]: author: (Ben Nuttall https://opensource.com/users/bennuttall)
|
||||
|
||||
不喜欢 diff 么？试试 Meld 吧
|
||||
======
|
||||
Meld 是一个可视化 diff 工具，它可让你轻松比较和合并文件、目录、Git 仓库等的更改。
|
||||
![Person drinking a hat drink at the computer][1]
|
||||
|
||||
Meld 是我处理代码和数据文件的基本工具之一。它是一个图形化的 diff 工具，因此，如果你曾经使用过 **diff** 命令并难以理解输出，那么 [Meld][2] 可以为你提供帮助。
|
||||
|
||||
这是该项目网站的精彩描述：
|
||||
|
||||
>“ Meld 是面向开发人员的可视化 diff 和合并工具。Meld 帮助你比较文件、目录和版本控制的项目。它提供文件和目录的双向和三向比较，并支持许多流行的版本控制系统。“
|
||||
>
|
||||
>“ Meld 帮助你检查代码更改并了解补丁。它甚至可以帮助你弄清你一直在避免的合并中发生了什么。”
|
||||
|
||||
你可以使用以下命令在 Debian/Ubuntu 系统（包括 Raspbian）上安装 Meld：
|
||||
|
||||
|
||||
```
|
||||
`$ sudo apt install meld`
|
||||
```
|
||||
|
||||
在 Fedora 或类似产品上，是：
|
||||
|
||||
|
||||
```
|
||||
`$ sudo dnf install meld`
|
||||
```
|
||||
|
||||
Meld 是跨平台的，它有一个使用 [Chocolately][4] 包管理器的 [Windows 安装包][3]。尽管它在 macOS 上不受官方支持，但有[可用于 Mac 的版本][5]，你可以使用 Homebrew 安装：
|
||||
|
||||
|
||||
```
|
||||
`$ brew cask install meld`
|
||||
```
|
||||
|
||||
有关[其他系统][2]，请参见 Meld 的主页。
|
||||
|
||||
### Meld 对比 diff 命令
|
||||
|
||||
如果你有两个相似的文件（也许一个是另一个的修改版本），并想要查看它们之间的更改，那么可以在终端中运行 **diff** 命令查看它们的区别：
|
||||
|
||||
![diff output][6]
|
||||
|
||||
此例显示了 **conway1.py** 和 **conway2.py** 之间的区别。表明我：
|
||||
|
||||
* 删除了 [shebang][7] 和第二行
|
||||
* 从类声明中删除了 **(object)**
|
||||
* 为类添加了 docstring
|
||||
* 在方法中交换了 **alive** 和 **neighbours == 2** 的顺序
|
||||
|
||||
|
||||
这是使用 **meld** 命令的相同例子。你可以在命令行中运行以下命令进行相同的比较：
|
||||
|
||||
|
||||
```
|
||||
`$ meld conway1.py conway2.py`
|
||||
```
|
||||
|
||||
![Meld output][8]
|
||||
|
||||
Meld 更清晰！
|
||||
|
||||
你可以单击箭头（上下都行）轻松查看并合并文件之间的更改。你甚至可以实时编辑文件（在输入时，Meld 可以用作具有实时比较功能的简单文本编辑器）—仅在关闭窗口之前一定要保存。
|
||||
|
||||
你甚至可以比较和编辑三个不同的文件：
|
||||
|
||||
![Comparing three files in Meld][9]
|
||||
|
||||
### Meld 的 Git 认知
|
||||
|
||||
希望你正在使用 [Git][10] 之类的版本控制系统。如果是这样，那么你的比较不是在两个不同文件之间进行，而是要查找当前文件与 Git 历史文件之间的差异。Meld 理解这一点，因此，如果你运行 **meld conway.py**（Git 中有 **conway.py**），它将显示自上次 Git 提交以来所做的更改：
|
||||
|
||||
![Comparing Git files in Meld][11]
|
||||
|
||||
你可以看到当前版本（右侧）和仓库版本（左侧）之间的更改。你可以看到，自上次提交以来，我删除了一个方法，并添加了一个参数和一个循环。
|
||||
|
||||
如果你运行 **meld .**，你将看到当前目录（如果位于根目录，就是整个仓库）中的所有更改：
|
||||
|
||||
![Meld . output][12]
|
||||
|
||||
你会看到一个文件被修改，另一个文件未加入版本控制（这意味着它对 Git 是新的，因此在比较之前，我需要 **git add** 该文件），以及许多其他未修改的文件。顶部的图标提供了各种显示选项。
|
||||
|
||||
你还可以比较两个目录，这有时很方便：
|
||||
|
||||
![Comparing directories in Meld][13]
|
||||
|
||||
### 结论
|
||||
|
||||
即使是普通用户也会觉得 diff 的比较难以理解。我发现 Meld 提供的可视化在找出文件之间的更改方面有很大的不同。最重要的是，Meld 有一些有用的版本控制认知，可以帮助你在不考虑太多内容的情况下对 Git 提交进行比较。快来试试 Meld，并轻松解决问题。
|
||||
|
||||
* * *
|
||||
|
||||
_本文最初发表在 Ben Nuttall 的 [Tooling blog][14] 上，并经允许重新使用。_
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/20/3/meld
|
||||
|
||||
作者：[Ben Nuttall][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[geekpi](https://github.com/geekpi)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/bennuttall
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/coffee_tea_laptop_computer_work_desk.png?itok=D5yMx_Dr (Person drinking a hat drink at the computer)
|
||||
[2]: https://meldmerge.org/
|
||||
[3]: https://chocolatey.org/packages/meld
|
||||
[4]: https://opensource.com/article/20/3/chocolatey
|
||||
[5]: https://yousseb.github.io/meld/
|
||||
[6]: https://opensource.com/sites/default/files/uploads/diff-output.png (diff output)
|
||||
[7]: https://en.wikipedia.org/wiki/Shebang_(Unix)
|
||||
[8]: https://opensource.com/sites/default/files/uploads/meld-output.png (Meld output)
|
||||
[9]: https://opensource.com/sites/default/files/uploads/meld-3-files.png (Comparing three files in Meld)
|
||||
[10]: https://opensource.com/resources/what-is-git
|
||||
[11]: https://opensource.com/sites/default/files/uploads/meld-git.png (Comparing Git files in Meld)
|
||||
[12]: https://opensource.com/sites/default/files/uploads/meld-directory-changes.png (Meld . output)
|
||||
[13]: https://opensource.com/sites/default/files/uploads/meld-directory-compare.png (Comparing directories in Meld)
|
||||
[14]: https://tooling.bennuttall.com/meld/
|
||||
Loading…
Reference in New Issue
Block a user