今天的文章不是一個技術文,反而是探討身為一個軟體工程師,該怎麼撰寫相關的技術文件
鑑於 WFH (Work From Hoem) 習慣的興起,人與人面對面的溝通減少,這意味即時的訊息傳遞變少了,取而代之的是非同步的訊息傳遞,簡單來說就是技術文件。
好的技術文件能夠讓需要的人快速找到問題,解決疑惑,但是一個好的技術文件到底該怎麼寫,這部分其實非常困難,並不是向程式碼一樣可以 copy&paste 馬上看到成果的,反而是需要時間練習,將整個過程與思路消化起來,用自己習慣的語言與形式將其撰寫出來。
首先,作者非常推崇由 Google 撰寫的系列文章,Tech Writing Course,整個課程內容不到兩小時,從不同章節來跟大家分享如何撰寫技術文章
接者撰寫技術文章時,作者個人是喜歡 divio 這個平台,不過更重要的則是其推薦的分類模式,根據內容分類成四大項
1. Tutorials - 學習導向
2. How-To Guides - 問題解決導向
3. Explanation - 深度理解導向
4. Reference - 資運分享導向
Google: https://developers.google.com/tech-writing
Divio: https://www.divio.com/
最後寫作語法方面,作者認為寫出一個能夠被有效搜尋的文章是非常重要的,譬如透過 word 等方式上傳檔案到系統中反而是一個不利於搜尋的方式。
取而代之的是,作者認為可以採用 Markdown 類似的語法作為基礎去撰寫文章,這種方式對於維護與撰寫都相對容易
今天有任何 Diagrams 的畫圖需求,可以考慮使用 Mermaid 這套解決方案,對於 GitLab/Azure 的使用者來說,已經內建其中。 GitHub/Atlassian Confluence 則有相關的 Plugin 可以安裝使用
最後則是文章的樣版內容,針對特定的文章格式,已經有不少的範本可以參考,透過這些範本可以更清楚的去描述你的內容,讓整體文章看起來更佳簡潔與流暢
1. Software Architecture Review Template
2. Architecture Decision Record Template
3. Incident Postmortem Template
4. DevOps Runbook
5. Decision Template
6. Writing Guidelines
7. OKR Template
8. Etc.
有興趣的點選原文學習更多
https://medium.com/better-programming/best-practices-when-documenting-your-code-for-software-engineers-941f0897aa0
同時也有10000部Youtube影片,追蹤數超過2,910的網紅コバにゃんチャンネル,也在其Youtube影片中提到,...
「github markdown語法」的推薦目錄:
- 關於github markdown語法 在 矽谷牛的耕田筆記 Facebook 的最讚貼文
- 關於github markdown語法 在 軟體開發學習資訊分享 Facebook 的精選貼文
- 關於github markdown語法 在 Lizardman19 Game Live Channel Facebook 的精選貼文
- 關於github markdown語法 在 コバにゃんチャンネル Youtube 的精選貼文
- 關於github markdown語法 在 大象中醫 Youtube 的最讚貼文
- 關於github markdown語法 在 大象中醫 Youtube 的最佳解答
- 關於github markdown語法 在 Markdown Cheatsheet 中文版 - Discover gists · GitHub 的評價
- 關於github markdown語法 在 十分鐘快速掌握Markdown | 卡斯伯Blog - 前端 的評價
- 關於github markdown語法 在 啟用GitHub 存放庫的儀表板面板徽章狀態- Azure Boards 的評價
- 關於github markdown語法 在 【文章推薦】GitHub上Markdown語法的高級應用- 碼上快樂 的評價
- 關於github markdown語法 在 GitHub 中README.rd 的markdown 語法 - 小狐狸事務所 的評價
- 關於github markdown語法 在 有支援Github Flavored 的Markdown 語言 - Poy Chang 的評價
- 關於github markdown語法 在 如何實現Github markdown 目錄/頁內跳轉? - GetIt01 的評價
- 關於github markdown語法 在 Markdown 語法支援在很多的部落格編輯器、github 的readme... 的評價
- 關於github markdown語法 在 Markdown 語法支援在很多的部落格編輯器、github 的readme... 的評價
- 關於github markdown語法 在 【教學】VuePress+GitHub架網站(四)-用Markdown語法來撰寫 ... 的評價
- 關於github markdown語法 在 【Markdown】github的Markdown语法(GFM)_墩墩分墩 的評價
- 關於github markdown語法 在 Markdown文件高亮语法· GitHub秘籍(中文版) - 看云 的評價
- 關於github markdown語法 在 使用Hexo 搭配GitHub架設個人部落格 - Peienwu 演算法筆記 的評價
- 關於github markdown語法 在 README.md檔案github Markdown語言詳解md檔案用法和說明 的評價
- 關於github markdown語法 在 项目中常用的Markdown语法 - CSDN博客 的評價
- 關於github markdown語法 在 使用Octopress + GitHub 免費架設部落格,以Markdown 語法 ... 的評價
- 關於github markdown語法 在 GFM(GitHub Flavored Markdown)与标准Markdown的语法区别 的評價
- 關於github markdown語法 在 GitHub 嵌入youtube 影片之markdown 語法產生器 - 不專業網管 ... 的評價
- 關於github markdown語法 在 GitHub 嵌入youtube 影片之markdown 語法產生器 - 不專業網管 ... 的評價
- 關於github markdown語法 在 在GitHub Pages上撰寫Markdown文章的注意事項 - 大专栏 的評價
- 關於github markdown語法 在 使用Markdown在github上排版README.md - 老天尊的死期 的評價
- 關於github markdown語法 在 在GitHub Pages上撰寫Markdown文章的注意事項 的評價
- 關於github markdown語法 在 关于写作(1):GitHub支持的Markdown写作指南 - 掘金 的評價
- 關於github markdown語法 在 README文件语法解读,即Github Flavored Markdown语法介绍 的評價
- 關於github markdown語法 在 mson, 對象表示法的Markdown 語法 - 开发99LOGO 的評價
- 關於github markdown語法 在 架設部落格第一次就上手Hexo + Github + 自訂網域 的評價
- 關於github markdown語法 在 Github Flavored Markdown | Bingo | zhrbin 的評價
- 關於github markdown語法 在 原來Github上的README.md文件這麼有意思——Markdown ... 的評價
- 關於github markdown語法 在 观点|《GitHub 风格的Markdown 正式规范》发布 - Linux.中国 的評價
- 關於github markdown語法 在 Pandoc's Markdown 語法中文翻譯 - GitHub Wiki SEE 的評價
- 關於github markdown語法 在 markdown教程:高级语法——发布到github - bilibili 的評價
- 關於github markdown語法 在 github markdown语法讲解 - 徐霁的博客 的評價
- 關於github markdown語法 在 關於github的README.md怎麼寫呢? - 一些平鋪直敘技術相關文 的評價
- 關於github markdown語法 在 [译] GitHub 风格的Markdown 语法 - Linux公社 的評價
- 關於github markdown語法 在 為你自己學 Git - 第 292 頁 - Google 圖書結果 的評價
- 關於github markdown語法 在 第68 期 的評價
- 關於github markdown語法 在 Leanpub 自出版實戰: 從寫作到上架,將作品推向全世界! 的評價
- 關於github markdown語法 在 Web開發者一定要懂的駭客攻防術(電子書) - 第 53 頁 - Google 圖書結果 的評價
- 關於github markdown語法 在 开源月刊《HelloGitHub》第68 期 - V2EX 的評價
- 關於github markdown語法 在 : 如何在GitHub的MD markdown自述文件中添加空格? 的評價
github markdown語法 在 軟體開發學習資訊分享 Facebook 的精選貼文
想要一個乾淨,簡單,快速和安全的網站或部落格,並在 Github 上免費託管嗎?Jekyll 是最好的方式而且支援開發者最喜歡的 Markdown 語法。
>此課程附有英文字幕
https://softnshare.wordpress.com/…/jekyiimakefastsecuresta…/
github markdown語法 在 Lizardman19 Game Live Channel Facebook 的精選貼文
【學習】Twitch新介面的網頁編輯系統"Markdown"語法
說明:
以前Twitch舊版瀏覽介面編輯是可支援HTML網頁編碼去撰寫的,但在8/1起Twitch開始取消舊版介面系統改採新版瀏覽界面後就無法支援HTML碼了,所以今天我開始研究新瀏覽網頁語法"Markdown",Markdown是一個簡單化的網頁編碼標記語言,目前趁空檔時間研究了一下語法大致有個頭緒了,現在只差設計靈感,未來我會把舊版的介紹及評分資訊轉設計到新版瀏覽介面上,所以現在分享大家基本的Markdown語法知識,如果有興趣我未來也可以實況開課教大家怎麼弄出一個漂亮的新版瀏覽介面的圖文並茂介紹文來,以下介紹說明文章很長,如果真的對實況有興趣跟想了解的人再看吧。
Markdown語法簡介:
Markdown是一個輕量的標記語言, 主要用於讓人們可以不用HTML複雜繁長的語法就能夠標記格式而達到管理文件的目的. Markdown是由John Gruber跟Aaron Swartz所創造出來的. 他們希望能夠讓人們可以用易讀, 易寫的簡單文件格式, 透過工具格式化轉成HTML. 經過多年的發展, Markdown已經成為許多人做筆記的第一選擇了. 原因除了其簡潔直觀的語法還有就是長期來慢慢累積出來的周邊工具. Markdown已經不再僅僅只是用於標記基礎格式的語言了, 圍繞著Markdown產生出來的工具組已經可以讓這個標記語言作到細緻的排版. 已經有為數不少的人用Markdown來創造他們的數位著作. 知名的源碼版本控制服務網站GitHub用Markdown作為他們預設支援的文本格式. 其它還有許多的服務都支援Markdown作為他們優先支援的格式.
Markdown其實是 (1) 一種文本語法 (2) 一個轉化文件成HTML格式的軟體工具. 他的工具是用Perl寫成. 本文將帶領讀者瞭解關於Markdown的基礎跟基本功能. 本文將會使用Pandoc一個專門用來轉化標記語言的工具來示範Markdown. Pandoc不僅僅只支援Markdown還支援如LaTeX, Textile等標記語言. 有興趣的讀者在閒暇之餘也可以研究一下.
Twitch的Markdown語法說明:
http://help.twitch.tv/…/por…/articles/839490-markdown-basics
github markdown語法 在 十分鐘快速掌握Markdown | 卡斯伯Blog - 前端 的推薦與評價
大部分情況下Markdown 是用來撰寫程式語言相關的文檔,因為純文字的特性與程式碼一致,且可搭配標示符號來改變呈現格式,像是在Github 的文件中使用 ... ... <看更多>
github markdown語法 在 啟用GitHub 存放庫的儀表板面板徽章狀態- Azure Boards 的推薦與評價
您可以將Markdown 語法新增至GitHub 存放庫檔案, README.md 以顯示該存放庫中的看板面板狀態。 藉由在您的[儀表板] 設定中新增您選擇的語法來顯示 ... ... <看更多>
github markdown語法 在 Markdown Cheatsheet 中文版 - Discover gists · GitHub 的推薦與評價
譯註:可以參考這份中文版文件,有更詳盡的Markdown 語法說明;如果需要可以練習的線上編輯器,可以試試看HackMD。 目錄. Headers Emphasis Lists Links Images Code and ... ... <看更多>