作者：Yihui Xie
译者：郑宝童
日期：2021.06.17

5.5 Collaboration

Writing a book will almost surely involve more than a single person. You may have co-authors, and readers who give you feedback from time to time.

写一本书几乎肯定会涉及到不止一个人。您可能有合著者和不时向您提供反馈的读者。

Since all book chapters are plain-text files, they are perfect for version control tools, which means if all your co-authors and collaborators have basic knowledge of a version control tool like GIT, you can collaborate with them on the book content using these tools. In fact, collaboration with GIT is possible even if they do not know how to use GIT, because GitHub has made it possible to create and edit files online right in your web browser. Only one person has to be familiar with GIT, and that person can set up the book repository. The rest of the collaborators can contribute content online, although they will have more freedom if they know the basic usage of GIT to work locally.

由于所有书籍章节都是纯文本文件，因此它们非常适合版本控制工具，这意味着如果您的所有共同作者和合作者都具备 GIT 等版本控制工具的基本知识，您可以使用这些工具与他们就书籍内容进行协作工具。事实上，即使他们不知道如何使用 GIT，也可以通过 GIT 协作，因为 GitHub 使直接在您的 Web 浏览器中在线创建和编辑文件成为可能。只需要一个人熟悉 GIT，这个人就可以设置图书存储库。其余的合作者可以在线贡献内容，但如果他们知道 GIT 的基本用法以在本地工作，他们将拥有更多的自由。

Readers can contribute in two ways. One way is to contribute content directly, and the easiest way, is through GitHub pull requests if your book source is hosted on GitHub. Basically, any GitHub user can click the edit button on the page of an Rmd source file, edit the content, and submit the changes to you for your approval. If you are satisfied with the changes proposed (you can clearly see what exactly was changed), you can click a “Merge” button to merge the changes. If you are not satisfied, you can provide your feedback in the pull request, so the reader can further revise it according to your requirements. We mentioned the edit button in the GitBook style in Section 3.1.1. That button is linked to the Rmd source of each page, and can guide you to create the pull request. There is no need to write emails back and forth to communicate simple changes, such as fixing a typo.

读者可以通过两种方式做出贡献。一种方法是直接贡献内容，如果您的图书源托管在 GitHub 上，则最简单的方法是通过 GitHub 拉取请求。基本上，任何 GitHub 用户都可以单击 Rmd 源文件页面上的编辑按钮，编辑内容，并将更改提交给您以供您批准。如果您对提议的更改感到满意（您可以清楚地看到究竟更改了什么），您可以单击“Merge”按钮来合并更改。如果您不满意，您可以在 pull request 中提供您的反馈，以便读者根据您的要求进一步修改。我们在 3.1.1节提到了 GitBook 风格的编辑按钮。该按钮链接到每个页面的 Rmd 源，可以引导您创建拉取请求。无需来回编写电子邮件来传达简单的更改，例如修复错字。

Another way for readers to contribute to your book is to leave comments. Comments can be left in multiple forms: emails, GitHub issues, or HTML page comments. Here we use Disqus (see Section 4.1) as an example. Disqus is a service to embed a discussion area on your web pages, and can be loaded via JavaScript. You can find the JavaScript code after you register and create a new forum on Disqus, which looks like this:

读者为您的书做出贡献的另一种方式是发表评论。评论可以以多种形式留下：电子邮件、GitHub issues或 HTML 页面评论。这里我们以 Disqus（见 4.1节）。 Disqus 是一种在网页上嵌入讨论区的服务，可以通过 JavaScript 加载。在 Disqus 上注册并新建论坛后可以找到 JavaScript 代码，如下所示：

<div id="disqus_thread"></div>
<script>
(function() { // DON'T EDIT BELOW THIS LINE
var d = document, s = d.createElement('script');
s.src = '//yihui.disqus.com/embed.js';
s.setAttribute('data-timestamp', +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
<noscript>Please enable JavaScript to view the
<a href="https://disqus.com/?ref_noscript">
  comments powered by Disqus.</a></noscript>

Note that you will need to replace the name yihui with your own forum name (this name has to be provided when you create a new Disqus forum). You can save the code to an HTML file named, for example, disqus.html. Then you can embed it at the end of every page via the after_body option (Figure 5.3 shows what the discussion area looks like):
请注意，您需要将名称 yihui 替换为您自己的论坛名称（创建新的 Disqus 论坛时必须提供此名称）。您可以将代码保存到名为 disqus.html 的 HTML 文件中。然后，您可以通过 after_body 选项将其嵌入到每个页面的末尾（图 5.3 显示了讨论区的样子）：

---
output:
  bookdown::gitbook:
    includes:
      after_body: disqus.html
---

FIGURE 5.3: A book page with a discussion area.