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-

最后編輯于 ：
?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明：文章內容（如有圖片或視頻亦包括在內）由作者上傳并發布，文章內容僅代表作者本人觀點，簡書系信息發布平臺，僅提供信息存儲服務。