Foreword
最近在《GitHub + Markdown 的新輕型技術寫作模式速覽》中帶大家快速了解了一下 GitHub + Markdown 這種比較新的技術寫作模式诵姜。不出所料梅割，確實有些小伙伴在讀了上一篇分享后存在諸多疑惑與顧慮紧唱。
如果你已經(jīng)從事技術寫作多年碘橘，已經(jīng)用慣了某個典型的傳統(tǒng)工具涩哟，也沒必要對 GitHub + Markdown 這種低成本極敏捷的模式嗤之以鼻救鲤。它是一種被越來越多的技術型創(chuàng)新企業(yè)采用的文檔解決方案。
很多全球知名產(chǎn)品或項目的文檔方案都是使用的 GitHub + Markdown朴皆，例如 Docker蚂子，Kubernetes 等燥透，如果你沒聽說過，可以去官網(wǎng)看看它們的文檔币旧。此外践险，2017 年 10 月份在 Stuttgart 舉行的 tcworld conference 2017 上，也有與會嘉賓分享了 Markdown 與 GitHub 結合的文檔模式吹菱，講的都是一些特別基礎的東西巍虫。
附上嘉賓的 PPT 鏈接，語言為德語（可使用 Google Translate 輔助理解）鳍刷，感興趣的小伙伴可以去看一下：http://conferences.tekom.de/fileadmin/tx_doccon/slides/1792_Dr_Jekyll_und_Mr_Markdown_Dokumentieren_auf_GitHub.pdf
本文主要內容結構：
- 解答讀者提出的 GitHub + Markdown 模式相關的幾個問題
- 采用 GitHub + Markdown 模式的文檔呈現(xiàn)效果如何
- GitHub + Markdown 的個人使用體驗
GitHub + Markdown 模式的相關問題解答
問題 1：這種模式是只適合創(chuàng)業(yè)型的企業(yè)吧垫言？如果公司已經(jīng)有了 long established 的文檔樣式要求的話，這種寫作模式就不太適合了吧倾剿？
GitHub + Markdown 這種模式比較適用于創(chuàng)業(yè)公司，尤其是技術型的創(chuàng)業(yè)公司。但我認為前痘，也不能絕對地說它只適用于創(chuàng)業(yè)公司凛捏，而應該以一種發(fā)展的眼光來看問題。絕大多數(shù)公司都是從創(chuàng)業(yè)階段走過來的芹缔，數(shù)年之后或者十幾年之后坯癣，GitHub + Markdown 這種模式在技術寫作領域所占的比重很可能會越來越大。
跟大家分享這種技術寫作模式呢最欠，并不是說讓大家都轉換到這種寫作模式上來示罗。對于那些長久以來已經(jīng)有固定模式要求的公司來說，確實不適合芝硬，這也不是某一個 Technical Writer 可以想改就改的蚜点。另外，不同的公司對文檔交付物的展現(xiàn)形式有不同的要求拌阴，這也會影響寫作工具的選擇绍绘。
我更想傳達的意思是這樣的：作為一個希望成長的 Technical Writer，應該始終保持一種好奇心迟赃，了解技術傳播陪拘、技術寫作領域的發(fā)展動態(tài)，一些新模式的行業(yè)實踐纤壁，以及可提高自己工作效率的新工具等左刽，擴展自己的視野。
而不是工作年限在增長酌媒，卻只局限在自己工作所用的那一種工具上欠痴，對行業(yè)的發(fā)展全然不知。這樣很容易被不斷發(fā)展的世界和行業(yè)所淘汰哦~
問題 2：長文檔是否適用馍佑？對于多圖片和表格的支持如何斋否？
- GitHub + Markdown 這種模式可以很好地支持長文檔，對單個文檔的長度沒有限制拭荤。
這里有個問題茵臭，多長的文檔算長呢？如果跟用 XML 編輯器寫的 DITA 類型的一個 topic 相比的話舅世，那一篇 Markdown 文檔可以長出好多旦委。當然啦，文檔可長可短雏亚，全由 Writer 來決定缨硝，就好比給你提供了一張可滿足你基本需求的白紙，任憑你自由發(fā)揮罢低。 - GitHub + Markdown 模式可以較好地支持基本的圖片與表格需求查辩。
如果你對圖片與表格有一些額外的復雜需求胖笛，可以請前端工程師配合實現(xiàn)。下文會給大家看幾個圖片與表格的實例~
問題 3：支持的文檔輸出格式包括哪些呢宜岛？輸出 PDF 是否要借助其他工具长踊？
在 Markdown 編輯中寫完的單篇文檔可以直接導出為 HTML 和 PDF，例如 MacDown 編輯器萍倡。不過身弊，個人在實際工作中，目前暫時沒有將單篇 Markdown 文件導出為其它格式的需求列敲，因為大多數(shù)情況下阱佛，是將寫好或修改好的 Markdown 文件直接提交到 GitHub 上。
如果需要將一個產(chǎn)品的全部文檔導出為一個 PDF戴而，可以找前端工程師配合支持凑术。
問題 4：有沒有特別具體的 GitHub + Markdown 的使用流程？
在上一篇里填硕，給大家簡單列了下基本的流程麦萤，沒有詳細展開。不同的產(chǎn)品對于創(chuàng)建和修改文檔的步驟也會有一些差異扁眯。想實際操練的小伙伴壮莹，可以先自行在網(wǎng)上搜索一下相關流程，相信你一定可以找到姻檀。
采用 GitHub + Markdown 的文檔呈現(xiàn)效果如何命满？
采用 GitHub + Markdown 的文檔實踐很多，這里以 Docker绣版、Kubernetes 和 TiDB 的用戶文檔為例胶台，帶大家了解一下采用這種模式的文檔長什么樣子，圖片和表格的呈現(xiàn)如何杂抽，以及這種模式特有的一些文檔輔助功能诈唬。
- Docker Documentation: https://docs.docker.com/
- Kubernetes Documentation: https://kubernetes.io/docs/
- TiDB Documentation: https://www.pingcap.com/docs/
1. 文檔主頁的呈現(xiàn)
即便都采用 GitHub + Markdown，不同的產(chǎn)品文檔呈現(xiàn)效果也不同缩麸，這要看對文檔呈現(xiàn)的需求和設計了铸磅。采用這種模式，通常會需要前端工程師的支持杭朱，以實現(xiàn)一些較為高級的呈現(xiàn)效果阅仔。
一種典型的文檔頁面展現(xiàn)布局是：分為左中右三欄，左側為文檔導航目錄弧械，中間為文檔正文八酒，右側為當前頁面的導航。
2. 表格和圖片的呈現(xiàn)
在上文的問題解答中刃唐，已經(jīng)講述了 GitHub + Markdown 對表格的支持羞迷。下面給大家看下呈現(xiàn)效果~
- 表格
大多數(shù)情況下界轩，GitHub 上的內容與文檔官網(wǎng)上的內容呈現(xiàn)是一致的，但有時為了在官網(wǎng)上實現(xiàn)特定的呈現(xiàn)效果闭树，需要犧牲一下 GitHub 上內容的可讀性耸棒。例如：
- 圖片
一般來講，圖片的呈現(xiàn)在官網(wǎng)和 GitHub 上是一致的报辱，但也有少數(shù)情況不一致。例如单山，如果需要在圖片下方加個居中的圖片標題碍现，官網(wǎng)的顯示是正常的，GitHub 上會顯示在左側米奸，未完全解析昼接。
3. 文檔更新動態(tài)的呈現(xiàn)
采用 GitHub + Markdown 這種模式，可以將一篇文檔的更新動態(tài)呈現(xiàn)在官網(wǎng)的文檔頁面悴晰，即該篇文檔最近一次更新是什么時間慢睡。這個功能可以讓用戶知曉某個產(chǎn)品的文檔維護動態(tài)，有利于增加對產(chǎn)品的信心铡溪。文檔不斷在更新漂辐，不斷在改進，說明產(chǎn)品也在不斷改進棕硫。
4. 用戶參與和反饋的入口
采用 GitHub + Markdown 這種模式髓涯，可以與用戶便捷地互動，及時獲取用戶的反饋意見哈扮，讓用戶參與到文檔的改進中來纬纪。許多產(chǎn)品的官方文檔頁面都添加了收集用戶反饋或者讓用戶直接參與文檔修改的入口，示例如下：
- 收集用戶反饋：GitHub Issues
- 讓用戶參與文檔修改：GitHub Pull Requests
GitHub + Markdown 的個人使用體驗
至今滑肉，我已使用 GitHub + Markdown 一年多包各。個人體驗中最明顯的一點是：提交或修改文檔尤為簡單敏捷。
不過靶庙，若要將產(chǎn)品的全部用戶文檔導出為 PDF问畅，實現(xiàn)起來并不簡單，很可能不是一般的 Technical Writer 可以解決的惶洲。這時按声，就只能提需求然后尋求技術小伙伴的支持了。
所以恬吕，這種模式并不一定適合所有的產(chǎn)品签则。它是一種新的輕型敏捷的技術文檔寫作模式，但到底要不要選擇這種模式铐料，需要綜合考慮實際的文檔需求渐裂、成本和時間等再做決定豺旬。
Afterword
無論從事什么工作，都應該時刻保持好奇心柒凉，及時了解行業(yè)發(fā)展動態(tài)族阅，以一種開放的心態(tài)去對待新事物。要不斷學習與個人發(fā)展相關的新技能膝捞，因為不進則退哦坦刀。
附本文示例鏈接
表格呈現(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
文檔更新動態(tài)示例鏈接：
- https://kubernetes.io/docs/concepts/storage/persistent-volumes/
- https://www.pingcap.com/docs/op-guide/ansible-deployment/
用戶參與和反饋示例鏈接：
- 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
你可能想讀：
技術文檔誕生記 | 完整的技術寫作流程是怎樣的？
Technical Writer 可提供的交付物有哪些蔬咬？
Technical Writer 日常工作中好用的小工具
如何使用顏色來提高技術文檔的可讀性鲤遥？
技術翻譯需要有 Technical Writer 的 sense
深度解析關于技術翻譯的六個認知誤區(qū)
如何讓你的內容輸出更加專業(yè)更有設計感？
書單 | 有哪些技術傳播從業(yè)者必知必看的書籍林艘？
有哪些適合技術傳播從業(yè)者關注的優(yōu)質博客盖奈？（一）
有哪些適合技術傳播從業(yè)者關注的優(yōu)質博客？（二）
經(jīng)驗分享 | 來自 11 位 Technical Writer 前輩的職業(yè)發(fā)展建議（上篇）
經(jīng)驗分享 | 來自 11 位 Technical Writer 前輩的職業(yè)發(fā)展建議（下篇）
英語技術文檔的標題到底該大寫還是小寫狐援？
如何使用正則表達式批量添加和刪除字符钢坦？
Markdown：寫技術文檔、個人博客和讀書筆記都很好用的輕量級標記語言
如何為 Markdown 文件自動生成目錄啥酱？
技術寫作實例解析 | 簡潔即是美
兩分鐘趣味解讀 Technical Writer
若脫離理解爹凹，直譯得再正確又有何意？
優(yōu)質譯文不應止于正確懈涛，還要 Well-Organized
Technical Writer 需要 Technical 到會寫代碼嗎逛万？
寫在入職技術型創(chuàng)業(yè)公司 PingCAP 一個月之后
揭秘 Technical Writer 的工作環(huán)境 | 加入 PingCAP 五個月的員工體驗記
-END-
