Technical Writer 想参与开源项目为文档做贡献，需提前掌握哪些知识？

Foreword

自前段时间分享了 Google 的 2019 Season of Docs 项目之后，业界的一些 Technical Writer (TW) 对参与开源项目的文档表现出了极大的兴趣。

很多小伙伴都希望能够在业余时间了解技术写作领域新的解决方案 (GitHub + Markdown)，实际参与开源项目来亲身体验，从而不断提升自身的技术写作技能。

然而，已工作的小伙伴们平时有日常工作，又担心没有那么多集中的时间来参与 Season of Docs 项目，于是便向我打听怎么参与 PingCAP 的开源项目 TiDB。

这里说明一下：PingCAP 是我现在任职的公司，老读者应该都知道。TiDB 是 PingCAP 的一个开源项目，做的是分布式 NewSQL (HTAP) 数据库。

其中一个 TW 妹纸说“超级想在工作外多锻炼自己”，我也特别开心能遇到一些不断提升自己、满满正能量的人。于是，我给几个找过来的同学承诺，会写一个如何给 TiDB 贡献文档的指南。

其实，在 GitHub 上 pingcap/community 库中，早已有 Contribution Guide，里面描述了命令行版的通用步骤：https://github.com/pingcap/community/blob/master/CONTRIBUTING.md

考虑到大多数的 Technical Writer 多是语言背景，没有任何技术背景，如果直接给大家说具体步骤的话，可能会一头雾水。

所以，建议大家先了解一些 GitHub 和 Markdown 的基础知识，以便于快速上手。这样，之后给大家分享具体的操作步骤时，就不会感到看得云里雾里了。当然，如果你对 Git 和 GitHub 很熟悉，可以直接参考命令行版哦~

附上我之前关于 GitHub 和 Markdown 的分享：

需要了解的一些术语

本文主要介绍一些常用常见的术语，你也可以去 GitHub 的 Glossary 里查看更多：

Git

Git 是一个免费的开源分布式版本控制系统，可快速高效地处理各种大小项目。要了解更多可查看：https://git-scm.com/

该网页还提供了免费的 Git 相关的书 Pro Git，可免费在线阅读，有多种语言版本。如果你有兴趣深入了解 Git，可以看下；如果你没兴趣了解太多，可以略过，直接往下看。

Pro Git 英文版

Pro Git 中文版

GitHub

GitHub 是一个基于网络的提供 Git 版本控制和托管服务的平台。网址为：https://github.com/ 我之前的分享里有较为详细的介绍。

我的个人主页是：https://github.com/lilin90，与 2018 年相比还是有一些小变化。

Branch

Branch 即分支，可以理解为一个库 (repository) 的平行版本。分支包含在库中，但是不会影响主分支 (即 master branch)。通常会在新建的分支上进行内容的修改，然后再将修改提交到 master 分支上。

以 https://github.com/pingcap/docs 为例，其分支如下图所示：

Commit

Commit 即你的修改，一个 commit 可以理解为一次改动。

示例如下：

Fork

Fork 的图标是个叉的形状，可以理解为复制一份。通过点击 Fork，可以将一个 repository 复制一份到个人账号下，个人复制的仓库中的修改不会影响原库。

Issue

如果你有一些优化建议，发现了一个 bug，或者想反馈一些问题，都可以提一个 issue。

Markdown

Markdown 是一种轻量级标记语言，详细介绍参考该分享。

Merge

Merge 即合并，指将一个 branch 中的修改合并到另一个 branch 中。常见的如将一个 branch 里的修改合并到 master branch 中。GitHub 官方介绍：https://help.github.com/en/articles/merging-a-pull-request

Pull Request

Pull Request 通常简称为 PR，是指用户提交的修改申请，一个 Pull Request 里可以包含多个 commit。

Repository

Repository 是 GitHub 上最基本的元素，可以理解为一个项目文件夹。中文里可称作“仓库”或“库”。Repository 里包含了所有的项目文件，以及每个文件的修改历史。它可以是 public 的，也可以是 private 的。

Afterword

以上便是一些基本的术语，并未涵盖所有，有些术语可以在实际提 Pull Request 的过程中更真切地理解。比如，Pull 和 Push，Pull 指将远程的修改拉取合并到本地，Push 则指将本地的修改推到远程仓库。

如果你想参与开源项目，为开源项目贡献文档，获得另一种不同的 Technical Writer 体验，拓展自己的技能树，可以先从本文分享的基础知识开始。之后，我会跟大家分享简单易上手的 GitHub 客户端版的操作步骤，让跃跃欲试的同学看完就可以行动起来。

你可能想读：

技术文档诞生记 | 完整的技术写作流程是怎样的？
Technical Writer 可提供的交付物有哪些？
GitHub + Markdown 的新轻型技术写作模式速览
 GitHub + Markdown 的技术文档方案深度解析
 Technical Writer 日常工作中好用的小工具
 技术传播人士应该知道的色彩搭配常识
 如何使用颜色来提高技术文档的可读性？
Technical Writer 如何 Review 技术文档？| 重细节+全局观
 技术翻译需要有 Technical Writer 的 sense
深度解析关于技术翻译的六个认知误区
 如何让你的内容输出更加专业更有设计感？
书单 | 有哪些技术传播从业者必知必看的书籍？
有哪些适合技术传播从业者关注的优质博客？（一）
有哪些适合技术传播从业者关注的优质博客？（二）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（上篇）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（下篇）
技术传播沙龙精彩分享 | 高校老师与行业大牛谈“互联网技术写作”
英语技术文档的标题到底该大写还是小写？
不同阶段如何应对 Technical Writer 的职业顾虑或烦恼？
如何使用正则表达式批量添加和删除字符？
英语技术文档中如何正确使用时态？
英语技术文档中如何正确使用人称？
英语技术文档中如何正确使用无序列表和有序列表？
Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
 如何为 Markdown 文件自动生成目录？
技术写作实例解析 | 简洁即是美
 两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
优质译文不应止于正确，还要 Well-Organized
Technical Writer 需要 Technical 到会写代码吗？
如何利用 GitHub Pages 和 Hugo 轻松搭建个人博客？
写在入职技术型创业公司 PingCAP 一个月之后
 揭秘 Technical Writer 的工作环境 | 加入 PingCAP 五个月的员工体验记

-END-