Foreword
最近在《GitHub + Markdown 的新輕型技術(shù)寫(xiě)作模式速覽》中帶大家快速了解了一下 GitHub + Markdown 這種比較新的技術(shù)寫(xiě)作模式。不出所料，確實(shí)有些小伙伴在讀了上一篇分享后存在諸多疑惑與顧慮。
如果你已經(jīng)從事技術(shù)寫(xiě)作多年，已經(jīng)用慣了某個(gè)典型的傳統(tǒng)工具，也沒(méi)必要對(duì) GitHub + Markdown 這種低成本極敏捷的模式嗤之以鼻。它是一種被越來(lái)越多的技術(shù)型創(chuàng)新企業(yè)采用的文檔解決方案。
很多全球知名產(chǎn)品或項(xiàng)目的文檔方案都是使用的 GitHub + Markdown，例如 Docker，Kubernetes 等，如果你沒(méi)聽(tīng)說(shuō)過(guò)，可以去官網(wǎng)看看它們的文檔。此外，2017 年 10 月份在 Stuttgart 舉行的 tcworld conference 2017 上，也有與會(huì)嘉賓分享了 Markdown 與 GitHub 結(jié)合的文檔模式，講的都是一些特別基礎(chǔ)的東西。
附上嘉賓的 PPT 鏈接，語(yǔ)言為德語(yǔ)（可使用 Google Translate 輔助理解），感興趣的小伙伴可以去看一下：http://conferences.tekom.de/fileadmin/tx_doccon/slides/1792_Dr_Jekyll_und_Mr_Markdown_Dokumentieren_auf_GitHub.pdf
本文主要內(nèi)容結(jié)構(gòu)：
- 解答讀者提出的 GitHub + Markdown 模式相關(guān)的幾個(gè)問(wèn)題
- 采用 GitHub + Markdown 模式的文檔呈現(xiàn)效果如何
- GitHub + Markdown 的個(gè)人使用體驗(yàn)
GitHub + Markdown 模式的相關(guān)問(wèn)題解答
問(wèn)題 1：這種模式是只適合創(chuàng)業(yè)型的企業(yè)吧？如果公司已經(jīng)有了 long established 的文檔樣式要求的話(huà)，這種寫(xiě)作模式就不太適合了吧？
GitHub + Markdown 這種模式比較適用于創(chuàng)業(yè)公司，尤其是技術(shù)型的創(chuàng)業(yè)公司。但我認(rèn)為，也不能絕對(duì)地說(shuō)它只適用于創(chuàng)業(yè)公司，而應(yīng)該以一種發(fā)展的眼光來(lái)看問(wèn)題。絕大多數(shù)公司都是從創(chuàng)業(yè)階段走過(guò)來(lái)的，數(shù)年之后或者十幾年之后，GitHub + Markdown 這種模式在技術(shù)寫(xiě)作領(lǐng)域所占的比重很可能會(huì)越來(lái)越大。
跟大家分享這種技術(shù)寫(xiě)作模式呢，并不是說(shuō)讓大家都轉(zhuǎn)換到這種寫(xiě)作模式上來(lái)。對(duì)于那些長(zhǎng)久以來(lái)已經(jīng)有固定模式要求的公司來(lái)說(shuō)，確實(shí)不適合，這也不是某一個(gè) Technical Writer 可以想改就改的。另外，不同的公司對(duì)文檔交付物的展現(xiàn)形式有不同的要求，這也會(huì)影響寫(xiě)作工具的選擇。
我更想傳達(dá)的意思是這樣的：作為一個(gè)希望成長(zhǎng)的 Technical Writer，應(yīng)該始終保持一種好奇心，了解技術(shù)傳播、技術(shù)寫(xiě)作領(lǐng)域的發(fā)展動(dòng)態(tài)，一些新模式的行業(yè)實(shí)踐，以及可提高自己工作效率的新工具等，擴(kuò)展自己的視野。
而不是工作年限在增長(zhǎng)，卻只局限在自己工作所用的那一種工具上，對(duì)行業(yè)的發(fā)展全然不知。這樣很容易被不斷發(fā)展的世界和行業(yè)所淘汰哦~
問(wèn)題 2：長(zhǎng)文檔是否適用？對(duì)于多圖片和表格的支持如何？
- GitHub + Markdown 這種模式可以很好地支持長(zhǎng)文檔，對(duì)單個(gè)文檔的長(zhǎng)度沒(méi)有限制。
這里有個(gè)問(wèn)題，多長(zhǎng)的文檔算長(zhǎng)呢？如果跟用 XML 編輯器寫(xiě)的 DITA 類(lèi)型的一個(gè) topic 相比的話(huà)，那一篇 Markdown 文檔可以長(zhǎng)出好多。當(dāng)然啦，文檔可長(zhǎng)可短，全由 Writer 來(lái)決定，就好比給你提供了一張可滿(mǎn)足你基本需求的白紙，任憑你自由發(fā)揮。 - GitHub + Markdown 模式可以較好地支持基本的圖片與表格需求。
如果你對(duì)圖片與表格有一些額外的復(fù)雜需求，可以請(qǐng)前端工程師配合實(shí)現(xiàn)。下文會(huì)給大家看幾個(gè)圖片與表格的實(shí)例~
問(wèn)題 3：支持的文檔輸出格式包括哪些呢？輸出 PDF 是否要借助其他工具？
在 Markdown 編輯中寫(xiě)完的單篇文檔可以直接導(dǎo)出為 HTML 和 PDF，例如 MacDown 編輯器。不過(guò)，個(gè)人在實(shí)際工作中，目前暫時(shí)沒(méi)有將單篇 Markdown 文件導(dǎo)出為其它格式的需求，因?yàn)榇蠖鄶?shù)情況下，是將寫(xiě)好或修改好的 Markdown 文件直接提交到 GitHub 上。
如果需要將一個(gè)產(chǎn)品的全部文檔導(dǎo)出為一個(gè) PDF，可以找前端工程師配合支持。
問(wèn)題 4：有沒(méi)有特別具體的 GitHub + Markdown 的使用流程？
在上一篇里，給大家簡(jiǎn)單列了下基本的流程，沒(méi)有詳細(xì)展開(kāi)。不同的產(chǎn)品對(duì)于創(chuàng)建和修改文檔的步驟也會(huì)有一些差異。想實(shí)際操練的小伙伴，可以先自行在網(wǎng)上搜索一下相關(guān)流程，相信你一定可以找到。
采用 GitHub + Markdown 的文檔呈現(xiàn)效果如何？
采用 GitHub + Markdown 的文檔實(shí)踐很多，這里以 Docker、Kubernetes 和 TiDB 的用戶(hù)文檔為例，帶大家了解一下采用這種模式的文檔長(zhǎng)什么樣子，圖片和表格的呈現(xiàn)如何，以及這種模式特有的一些文檔輔助功能。
- Docker Documentation: https://docs.docker.com/
- Kubernetes Documentation: https://kubernetes.io/docs/
- TiDB Documentation: https://www.pingcap.com/docs/
1. 文檔主頁(yè)的呈現(xiàn)
即便都采用 GitHub + Markdown，不同的產(chǎn)品文檔呈現(xiàn)效果也不同，這要看對(duì)文檔呈現(xiàn)的需求和設(shè)計(jì)了。采用這種模式，通常會(huì)需要前端工程師的支持，以實(shí)現(xiàn)一些較為高級(jí)的呈現(xiàn)效果。
一種典型的文檔頁(yè)面展現(xiàn)布局是：分為左中右三欄，左側(cè)為文檔導(dǎo)航目錄，中間為文檔正文，右側(cè)為當(dāng)前頁(yè)面的導(dǎo)航。
2. 表格和圖片的呈現(xiàn)
在上文的問(wèn)題解答中，已經(jīng)講述了 GitHub + Markdown 對(duì)表格的支持。下面給大家看下呈現(xiàn)效果~
- 表格
大多數(shù)情況下，GitHub 上的內(nèi)容與文檔官網(wǎng)上的內(nèi)容呈現(xiàn)是一致的，但有時(shí)為了在官網(wǎng)上實(shí)現(xiàn)特定的呈現(xiàn)效果，需要犧牲一下 GitHub 上內(nèi)容的可讀性。例如：
- 圖片
一般來(lái)講，圖片的呈現(xiàn)在官網(wǎng)和 GitHub 上是一致的，但也有少數(shù)情況不一致。例如，如果需要在圖片下方加個(gè)居中的圖片標(biāo)題，官網(wǎng)的顯示是正常的，GitHub 上會(huì)顯示在左側(cè)，未完全解析。
3. 文檔更新動(dòng)態(tài)的呈現(xiàn)
采用 GitHub + Markdown 這種模式，可以將一篇文檔的更新動(dòng)態(tài)呈現(xiàn)在官網(wǎng)的文檔頁(yè)面，即該篇文檔最近一次更新是什么時(shí)間。這個(gè)功能可以讓用戶(hù)知曉某個(gè)產(chǎn)品的文檔維護(hù)動(dòng)態(tài)，有利于增加對(duì)產(chǎn)品的信心。文檔不斷在更新，不斷在改進(jìn)，說(shuō)明產(chǎn)品也在不斷改進(jìn)。
4. 用戶(hù)參與和反饋的入口
采用 GitHub + Markdown 這種模式，可以與用戶(hù)便捷地互動(dòng)，及時(shí)獲取用戶(hù)的反饋意見(jiàn)，讓用戶(hù)參與到文檔的改進(jìn)中來(lái)。許多產(chǎn)品的官方文檔頁(yè)面都添加了收集用戶(hù)反饋或者讓用戶(hù)直接參與文檔修改的入口，示例如下：
- 收集用戶(hù)反饋：GitHub Issues
- 讓用戶(hù)參與文檔修改：GitHub Pull Requests
GitHub + Markdown 的個(gè)人使用體驗(yàn)
至今，我已使用 GitHub + Markdown 一年多。個(gè)人體驗(yàn)中最明顯的一點(diǎn)是：提交或修改文檔尤為簡(jiǎn)單敏捷。
不過(guò)，若要將產(chǎn)品的全部用戶(hù)文檔導(dǎo)出為 PDF，實(shí)現(xiàn)起來(lái)并不簡(jiǎn)單，很可能不是一般的 Technical Writer 可以解決的。這時(shí)，就只能提需求然后尋求技術(shù)小伙伴的支持了。
所以，這種模式并不一定適合所有的產(chǎn)品。它是一種新的輕型敏捷的技術(shù)文檔寫(xiě)作模式，但到底要不要選擇這種模式，需要綜合考慮實(shí)際的文檔需求、成本和時(shí)間等再做決定。
Afterword
無(wú)論從事什么工作，都應(yīng)該時(shí)刻保持好奇心，及時(shí)了解行業(yè)發(fā)展動(dòng)態(tài)，以一種開(kāi)放的心態(tài)去對(duì)待新事物。要不斷學(xué)習(xí)與個(gè)人發(fā)展相關(guān)的新技能，因?yàn)椴贿M(jìn)則退哦。
附本文示例鏈接
表格呈現(xiàn)示例鏈接：
- https://docs.docker.com/ee/supported-platforms/#on-premises
- https://github.com/docker/docker.github.io/blob/master/ee/supported-platforms.md#on-premises
- https://www.pingcap.com/docs/op-guide/recommendation/
- https://github.com/pingcap/docs/blob/master/op-guide/recommendation.md
圖片呈現(xiàn)示例鏈接：https://docs.docker.com/ee/#orchestration-platform-features
文檔更新動(dòng)態(tài)示例鏈接：
- https://kubernetes.io/docs/concepts/storage/persistent-volumes/
- https://www.pingcap.com/docs/op-guide/ansible-deployment/
用戶(hù)參與和反饋示例鏈接：
- https://kubernetes.io/docs/concepts/storage/persistent-volumes/
- https://github.com/kubernetes/website/edit/master/content/en/docs/concepts/storage/persistent-volumes.md
- https://docs.docker.com/ee/supported-platforms/
- https://github.com/docker/docker.github.io/edit/master/ee/supported-platforms.md
你可能想讀：
技術(shù)文檔誕生記 | 完整的技術(shù)寫(xiě)作流程是怎樣的？
Technical Writer 可提供的交付物有哪些？
Technical Writer 日常工作中好用的小工具
如何使用顏色來(lái)提高技術(shù)文檔的可讀性？
技術(shù)翻譯需要有 Technical Writer 的 sense
深度解析關(guān)于技術(shù)翻譯的六個(gè)認(rèn)知誤區(qū)
如何讓你的內(nèi)容輸出更加專(zhuān)業(yè)更有設(shè)計(jì)感？
書(shū)單 | 有哪些技術(shù)傳播從業(yè)者必知必看的書(shū)籍？
有哪些適合技術(shù)傳播從業(yè)者關(guān)注的優(yōu)質(zhì)博客？（一）
有哪些適合技術(shù)傳播從業(yè)者關(guān)注的優(yōu)質(zhì)博客？（二）
經(jīng)驗(yàn)分享 | 來(lái)自 11 位 Technical Writer 前輩的職業(yè)發(fā)展建議（上篇）
經(jīng)驗(yàn)分享 | 來(lái)自 11 位 Technical Writer 前輩的職業(yè)發(fā)展建議（下篇）
英語(yǔ)技術(shù)文檔的標(biāo)題到底該大寫(xiě)還是小寫(xiě)？
如何使用正則表達(dá)式批量添加和刪除字符？
Markdown：寫(xiě)技術(shù)文檔、個(gè)人博客和讀書(shū)筆記都很好用的輕量級(jí)標(biāo)記語(yǔ)言
如何為 Markdown 文件自動(dòng)生成目錄？
技術(shù)寫(xiě)作實(shí)例解析 | 簡(jiǎn)潔即是美
兩分鐘趣味解讀 Technical Writer
若脫離理解，直譯得再正確又有何意？
優(yōu)質(zhì)譯文不應(yīng)止于正確，還要 Well-Organized
Technical Writer 需要 Technical 到會(huì)寫(xiě)代碼嗎？
寫(xiě)在入職技術(shù)型創(chuàng)業(yè)公司 PingCAP 一個(gè)月之后
揭秘 Technical Writer 的工作環(huán)境 | 加入 PingCAP 五個(gè)月的員工體驗(yàn)記
-END-
