中文文檔規範化,zh.md 來幫你!丨TiDB Hackathon 2020 優秀項目分享

近日,由 TiDB 社區主辦,專屬於全球開發者與技術愛好者的頂級挑戰賽事——TiDB Hackathon 2020 比賽圓滿落幕。今年是 TiDB Hackathon 第四次舉辦,參賽隊伍規模創歷屆之最,共有 45 支來自全球各地的隊伍報名,首次實現全球聯動。經過 2 天時間的極限挑戰, 大賽湧現出不少令人激動的項目。爲了讓更多朋友瞭解這些參賽團隊背後的故事,我們將開啓 TiDB Hackathon 2020 優秀項目分享系列,本次訪談我們邀請到了 zh.md 的兩位隊員:來自 Cisco 的研發工程師王鵬翰、來自 PingCAP I18N 團隊的 Coco,以及 Hackathon 特邀評委:來自青雲 QingCloud 的張雁飛老師,共同談談他們對於 zh.md 的看法。

這也是一次專業工程師 + Tech Writer + 用戶的三方會談,希望通過本次訪談和思想碰撞,讓大家對於中文技術文檔的寫作和自動化改進有全新的看法。

緣起:一份優雅的中文技術文檔是怎樣煉成的?

談及爲什麼會對 zh.md 格外關注時,評委老師張雁飛表示:**技術文檔的規範化是吸引用戶,樹立品牌非常重要的一環。**一份格式混亂、翻譯參差不齊的文檔會給產品大大減分。無論產品本身有多麼優秀,技術文檔這“最後一公里”對於用戶的體驗都是至關重要的。

zh.md 的隊長王鵬翰作爲一個 OpenTelemetry 技術愛好者,翻譯文檔時發現許多中文文檔翻譯得參差不齊,格式混亂,就連 CNCF 老大哥 K8S 的技術文檔,僅僅是“樣式指南”中出現的格式問題就已經可以用令人頭大來形容了。不好用的技術文檔往往會把 open source 的軟件變成一個 source open 卻難以上手的軟件。

恰逢 TiDB Hackathon 2020 正在徵集項目,王鵬翰想到 PingCAP 的文檔在國內的開源領域是十分專業的。就算有專業的 Tech Writer 維護,做到風格的統一也不容易,PingCAP 是怎麼做到的?仔細閱讀之後,他找到了一份 PingCAP 維護的 30 多頁的風格指南。這份風格指南非常詳盡,給了他非常大的啓發。但對於大多數人來說,逐字逐句地閱讀一份風格指南成本過高,而且也難以記清其中的規則,因此自動化的文檔工具就成爲了一個值得探索的方向。

王鵬翰有些激動,他參加過大大小小 20 多次的 Hackathon 比賽,他認爲這個 idea 可以排得上前三名。

動手:工程師 + Tech Writer 一起出發

——那就行動起來吧。

王鵬翰很快通過社區與 PingCAP 文檔風格指南的作者:PingCAP I18N 團隊的 Coco 同學取得了聯繫。他們很快達成了共識:希望借 Hackathon 這個機會,讓更多人認識到開源軟件以及 2B 公司技術文檔規範的重要性。

Coco 作爲項目的產品經理+測試,規劃了或許是中文社區裏第一份詳盡的中文文檔寫作風格指南,和王鵬翰一起設計了或許是中文社區裏第一個中文標點符號檢測工具、第一個中英文混排排版檢測與優化工具;並且在短時間內設計了測試方法,實現對文檔問題的排查,檢驗了工具的能力。

技術上,王鵬翰實現了一套中文文檔分析與檢測工具,基於 AST(抽象語法樹)和分詞,系統地對文檔進行掃描與診斷,評估文檔質量並對其進行優化和修復,並且基於文檔分析結果,使用統計學/ NLP 等工具,輔助作者寫出符合風格規範的文檔,還可以使用第三方 API,對文本進行中英文錯誤檢測。

目前針對純文本的 linter,主要有以下兩種:

  • 文檔格式的 linter,例如 remark.js、markdownlint 等工具

  • 英文語言的 linter,着重在檢測風格和拼寫上,例如 vale、textlint 等工具

相較於英文文檔,中文文檔的 linter 語法要複雜很多。當前市面上針對中文文檔的 linter,還處於早期階段,尚無成熟的方案。在此次 Hackathon 中,王鵬翰首先做了語境 -> 實例 -> 字的 AST,然後針對標點符號、中文詞彙(重組回句子後進行分詞)、英語詞彙做跳鏈索引。相較於利用正則表達式制定規則的傳統方案,有數量級的性能提升,同時保證了高擴展性。

專業 Tech Writer 與開源社區活躍貢獻者聯手打造的 zh.md 新鮮出爐,用 TiDB 的官方文檔小試牛刀,居然發現了 600 多處拼寫錯誤、5000 多處排版問題。

這個工作,沒白做!

關於項目的未來,他們希望這份工具可以繼續改進,應用於更廣闊的天地:

v0.1: pingcap/docs-cn 使用上 zh.md 工作流,優化文檔質量。[基本完成✅]

v1.0: PingCAP 旗下所有 repo 使用上 zh.md 工作流,優化文檔質量。

v1.x: 向 CNCF 推廣,幫助 CNCF 項目的中文文檔都使用上工作流,優化文檔質量。

v2.x: 提供 SaaS 服務,幫助各個技術公司的項目進行文檔輔助協作,輔助翻譯。幫助 2B 公司更好的文檔本地化。

Hackathon:不止是一場比賽

王鵬翰已經是一個 Hackathon 的老玩家了,這也是他第四次參加 TiDB Hackathon 了。

圖爲 2017、2019、2020 三屆 TiDB Hackathon 的紀念 T 恤

在此期間他的角色不斷轉變——

根據王鵬翰的描述,2017 年的“第 0 屆” TiDB Hackathon 是在一個贊助商公司的小食堂裏舉辦,只有四五十人蔘與。雖然條件略顯簡陋,但是在場的工程師用硬核乾貨的 Go 項目爲 TiDB 後續的 Hackathon 打下了一個“硬核”的基調。對於他自己來說,這屆 Hackathon 幫助他更好地掌握了當時還不是主流的 Go 語言,這讓他能夠輕易地上手 Kubernetes,參加雲原生的生態,爲以後的工作打下基礎。

2018 年他是一等獎項目 TiDB Batch and Streaming SQL(簡稱 TBSSQL)的一員,和崔秋、杜川兩位“大腿”一起,擴展了 TiDB 的 SQL 引擎,支持用戶以類似 StreamSQL 的語法將 Kafka, Pulsar 等外部數據源以流式表的方式接入 TiDB。讚歎於兩位大佬能力的同時,他作爲學習者,瞭解了 TiDB 的核心架構與運作原理。

2018 TiDB Hackathon 一等獎隊伍 TiBoys 合影

2019 年的他已經可以獨立運營項目了,他基於 TiDB Plugin Framework,爲 TiDB 增加大量用戶定製化的功能擴展方案,爲 TiDB 添加類似於 MySQL UDF 的功能。他提到:“可以說是前幾年的 Hackathon 給我的經驗讓我有能力在這一年開始獨立的寫一些基於 TiDB 的功能,給 TiDB 的代碼一些貢獻。”

**TiDB Hackathon 2020 對他來說更是意義非凡。**這一年的 Hackathon 中,他用一個能造福 TiDB 社區內外項目的 idea 獲得了三等獎;他還讓女朋友帶領“鴿了爽”隊也一起參加比賽,完成他去年對 Plugin Framework 實現未盡的探索。

對王鵬翰來說,參加 Hackathon 算是對自己的一個總結,也是給自己的 idea 一個落地的機會。相比於其它許多 Hackathon 項目宣講會的形式,TiDB Hackathon 更注重硬核的技術比拼,不僅看 idea 的好壞,更注重實現的效果。正如 PingCAP CTO 黃東旭開玩笑說的,PingCAP 是一家 Hackathon 驅動的公司。許多 Hackathon 中出彩的項目是會成爲 TiDB 的分支,甚至合到 TiDB 的主分支去的。

對 Coco 來說,這次 Hackathon 給了她一個 Tech Writer 以外的身份。怎樣通過技術手段減少中文文檔撰寫的工作量、自動地診斷和優化技術文檔,如何將一份 30 多頁的風格指南抽象成具體的自動化需求……這些都是全新的體驗。

張雁飛老師則是第一次以評委的身份出席 TiDB Hackathon。選手們對技術的狂熱追求也激發了他對代碼的熱情。比賽當天等待的過程中,他也對自己的 UDF 項目進行了重構優化,進行了一次自己的 Hackathon 探索。他更表示如果有機會,希望明年能夠以選手的身份參與到活動中。

另外此項目已經發布在了 https://github.com/tidb-incubator/zh.md 裏面,歡迎大家點擊下方【閱讀原文】前往體驗!

正如本屆大賽的主題「∞」,希望 TiDB Hackathon 在比賽之外,能夠給每一個人帶來無限可能。

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章