今天的文章不是一個技術文,反而是探討身為一個軟體工程師,該怎麼撰寫相關的技術文件
鑑於 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
「markdown mermaid」的推薦目錄:
- 關於markdown mermaid 在 矽谷牛的耕田筆記 Facebook 的最佳解答
- 關於markdown mermaid 在 BorntoDev Facebook 的最佳貼文
- 關於markdown mermaid 在 mermaid - Markdownish syntax for generating flowcharts ... 的評價
- 關於markdown mermaid 在 Include diagrams in your Markdown files with Mermaid - The ... 的評價
- 關於markdown mermaid 在 mermaid-js/mermaid: Generation of diagram and flowchart ... 的評價
- 關於markdown mermaid 在 GitHub Diagrams with Mermaid | Blog - Ardalis 的評價
- 關於markdown mermaid 在 GitHub 的Markdown 透過Mermaid 支援各種流程圖 的評價
- 關於markdown mermaid 在 GitHub's Mermaid support enables developers to quickly ... 的評價
- 關於markdown mermaid 在 Now, Github allows diagrams & flowcharts in markdown files 的評價
- 關於markdown mermaid 在 Is there an option to include external file in Mermaid Markdown? 的評價
- 關於markdown mermaid 在 How to Add Diagrams to GitHub Markdown Files 的評價
- 關於markdown mermaid 在 GitHub Markdown now Supports Mermaid Diagrams - DEV ... 的評價
- 關於markdown mermaid 在 How to Include Mermaid Diagrams in Your GitHub Project 的評價
- 關於markdown mermaid 在 Make Flowcharts on Github with Mermaid/Markdown (Bonus 的評價
- 關於markdown mermaid 在 Make Flowcharts on Github with Mermaid/Markdown (Bonus 的評價
- 關於markdown mermaid 在 GitHub Markdown now Supports Mermaid Diagrams - Waylon ... 的評價
- 關於markdown mermaid 在 再不用怕Markdown中的绘图了,GitHub官方支持 ... - 机器之心 的評價
- 關於markdown mermaid 在 Markdown Mermaid support - Hashnode 的評價
- 關於markdown mermaid 在 Github Writer now available with Mermaid support - CKEditor 的評價
- 關於markdown mermaid 在 再不用怕Markdown中的绘图了,GitHub官方支持Mermaid图表 ... 的評價
- 關於markdown mermaid 在 GitHub Supports Mermaid For Creating Diagrams - I ... 的評價
- 關於markdown mermaid 在 Support Mermaid (markdown) graph diagrams in .md files 的評價
- 關於markdown mermaid 在 Monsters Weekly 240 - Mermaid Diagrams on GitHub 的評價
markdown mermaid 在 BorntoDev Facebook 的最佳貼文
⚡️ เปลี่ยน Markdown สุดจะลายตาให้กลายเป็น Flowchart / Diagram ต่าง ๆ บน Visual Studio Code ได้ง่าย ๆ แค่ติดตั้ง "Markdown Preview Mermaid Support" !!
.
สำหรับใครอยากสร้าง Diagram / Flowchart ของตัวเองแต่เบื่อกับการลาก แปะ โยงเส้นวุ่นวายไปหมดแอดแนะนำตัวนี้เลย
.
https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid
.
เพราะเราแค่โฟกัสไปที่ Context เนื้อหาที่เราต้องการจะสร้างเท่านั้น ส่วนเรื่องจัดวางเขาจัดการให้เราหมดเลยย <3
.
ตัวนี้ใช้งานฟรีด้วยนะ ใครใช้แล้วดียังไงมาเล่าสู่กันฟังได้เลยครับผม ^_^
.
#BorntoDev - 🦖 Coding Academy ให้การพัฒนาเทคโนโลยีเป็นเรื่องง่ายสำหรับทุกคน
markdown mermaid 在 Include diagrams in your Markdown files with Mermaid - The ... 的推薦與評價
Mermaid is a JavaScript based diagramming and charting tool that takes Markdown-inspired text definitions and creates diagrams dynamically ... ... <看更多>
markdown mermaid 在 mermaid-js/mermaid: Generation of diagram and flowchart ... 的推薦與評價
Mermaid is a Javascript based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex ... ... <看更多>
markdown mermaid 在 mermaid - Markdownish syntax for generating flowcharts ... 的推薦與評價
Mermaid lets you create diagrams and visualizations using text and code. It is a Javascript based diagramming and charting tool that renders Markdown-inspired ... ... <看更多>