Skip to content

成為一名技術留跡者

小弟 Blog 陸陸續續也從 2013 年寫到現在了，從 roan.logdown.com 到現在的 blog.pichuang.com.tw 自己寫作風格好像一直以來都是差不多的，這邊分享一下幾個我覺得蠻有用的資訊

我為什麼要寫作?

寫作不是為了別人，是為了自己

很簡單，資訊太多，透過文字消化資訊和整理思緒

時間花費?

跟看文章完全不一樣，寫文章 非常花時間，通常我自己寫一篇都要坐在椅子上要寫上 2 - 3 小時，有些比較複雜的，要截圖翻書和找引用文件，可能 4 - 5 小時都有可能

所以我非常佩服寫書的大大們...

推薦使用套路?

  • 語法選擇: Markdown，基本上沒有什麼懸念，Markdown 文字移植性太好，到哪裡基本上都可以用，但缺點就是對於圖片處理不好，但身為一個大部分都是寫字居多的，沒什麼問題
  • 建立靜態網站: 現在要搞一個自己的 Blog 已經不是很麻煩的事情了，也不需要用到 Wordpress / Drupal 這種 CMS 比較大的等級，有個人 GitHub 帳號就可以建立靜態網頁，搭配 Hexo 或 Jekyll 或 Hugo 三個選一個使用，我是用 Hexo
  • 申請個人域名: .tw 結尾的應該不會太貴我記得，我個人是選 Gandi 域名商 (感恩 哈維 讚嘆 Haway)，掛載到 Cloudflare 的話就有 SSL 的連線能力囉

給工程師看的純技術文件寫作風格選擇?

請給我標準的技術文件規範

老實說，這個問題見仁見智，每個人的思緒理解和風格不同，所寫出來的用字和排版也會有很大的差異，但如果目標是要寫標準的技術文件的話，想要了解格式的話，倒是可以看看各大原廠的技術文件規範

Write the Docs 是一個關心技術文件規範的人所組成的社群，每年會有Conferences、Meetups，裡面有不少學習資源，條列幾個比較有名的風格文件給大家參考

  1. Microsoft Writing Stle Guide
  2. IBM DeveloperWorks Style Guide
  3. Red Hat Style Guide
  4. SUSE Documentation Style Guide
  5. Google Developer Documentation Style Guide

但實際上來說，你看完上面的所有文件，大概就是英文作文能力變好，實際上很難完全應用，因為畢竟自己寫文章跟這種大型組織要寫的文件是有點不一樣的，所以以下再提供幾個文件比較落地一點，但因為工作關係，所以會非常偏 Red Hat 的格式

有什麼教學網站嗎?

Every engineer is also writer

前陣子 Google 發布了一個 Technical Writing Courses 網站，主要是英文，分為 2 個課程

  1. 基礎技術寫作知識科普
  2. 中階技術寫作主題教學

個人是認為這是標準的英文寫作課 XD，對我還蠻有用的，以後可以嘗試寫點英文技術文件下來

除了教學網站，連基礎的技術文件網站模板都 OpenSource 了，可以參考以 Hugo 為底的 google/docsy 專案或者是相當知名的 mkdocs / VuePress，此外還弄了個 Season of Docs 供對於這類技術作家們的開源社群，不得不說 Google 真的是蠻有心的，整套包好好

寫作工具?

這也沒什麼好選的，基本上就是環繞 HackMD 的工具，HackMD 是我長久使用的 Ｍarkdown 以來最好用的一個平台，我看有些國外會議紀錄也都改用 HackMD 來做共筆

後話

我蠻鼓勵只要是 IT 技術從業人員，無論是在學還是就職者，都應該要花點時間把一些常遇到的技術或者是觀察記錄下來，寫多了其實最大的受益者真的不是別人，是自己。資訊量這麼大的狀況下，培養出個第二大腦是相當重要的，或許不需要像我這樣習慣寫作後公開，你也可以建立自己的私人 Wiki 或者是使用 HackMD 紀錄相關的資訊，好自己做個整理，臨時要用的時候是相當方便的

References