# 8/23(ㄧ) 每日任務： 善用「情境敘述」讓程式碼變得有意義

歡迎來到第五週的六角寫作王(≖‿ゝ≖)✧

禮拜一的心情想必很阿雜吧？

寫作其實跟人生一樣，有時候會很煩躁、想不出什麼酷東西做為文章情境。

但技術寫作的好處是：你不用管讀者閱讀的情緒好不好、感不感動，**有解決問題才是重點。**

但往往你會發現，自己的文章或是筆記，不但不能協助自己解決問題，反而讓自己更加混亂。

這中間到底是出了什麼問題？

別讓筆記淪為流水帳
---

技術寫作的重點在於，要用快速、簡潔的方式讓讀者**快速理解「問題」，並且提供適當的作法。**

這時候你就會想到：「啊！我用心智圖，或者列點式的語法筆記呀！一定超清楚！」

然而大部分的技術寫作文章，或甚至是自己為了學習所記錄的筆記，往往都**缺了「問題釐清」的文字敘述**。

一旦遇到難解的問題，大家就像考卷發下來一樣，只忙著把「答案」抄下來，而沒有抄題目，也**不會去分析**題目的要考的是什麼**邏輯**。

舉例來說，你今天學了一個新的語法，專門處理關鍵字篩選，於是你在筆記中列下所有的語法，但下一次你遇到同樣問題時，你只看到密密麻麻的程式碼。

const newList = this.productList.filter((item)=>item.match(keyword))

啊⋯⋯What is this?

結果你花時間抄了程式碼，這筆記最後卻像是沒有被檢討的期末考考卷一樣，被遺忘在角落。

技術寫作一定要帶入「情境敘述」
---

要讓文章更容易被理解、更容易打中讀者「痛點」，除了要附上完整的程式碼外，**你還需要解釋這個技術會在什麼狀況用到，或是程式碼本身的的撰寫邏輯。**

舉例來說，今天你學到了 JavaScript 的 AJAX 技巧，千萬不要貼了一行 Axios 的 CDN ，或是只寫了這樣：

let data = [];

function getData(){
    axios.get(api)
    .then(res=>data = res.data.result.records;)
    .catch(err =>console.log(err))
}

記得多少補一下**使用情境**，舉例來說：

> 1. 宣告一個變數名稱為 data 的空陣列，用來儲存遠端API接回來的資料。
> 2. 使用 axios 串接資料，並在接資料時運用 promise 的概念，在取得遠端資料後，將資料指給變數 data，用以後續渲染畫面。

其實寫這一串簡單的流程敘述，不會花你10分鐘，但我們往往就是一個**懶**字。

即便寫筆記當下**你的腦袋非常清楚**，你依然有很高的機會隔天就忘當初為什麼會這樣寫。

## 每日任務內容：

1. 請檢視自己自己活動以來撰寫的筆記中，是否有寫了程式碼，但沒有寫上「流程、使用情境」的狀況？如果沒有的話請補上，並將筆記連結一併附上後，回報至任務回報區中。

2. 別忘了一併回報今天**你執行「超級 mini 小目標」了沒？**

## 任務回報區：

> 任務回報範例：
>
> **0. Vivian:**
> 1. 在上切版直播班前，對於切版的流程不是很熟悉，卡了幾次關後，終於把容器的[開發流程](https://hackmd.io/@o9ZLEqeZQ8e7u_JXSPfjsQ/S1EW2d5R_/%2Fw93JvQZETfWLIZkNWw6aMg)紀錄下來，雖然花了點時間，但很值得。
> 2. 至今為止都有好好執行我的「超級 mini 小目標」，反正就是每天爆肝硬寫，有什麼難的？嗚嗚QAQ

**1. Lou:** 檢查了文章[使用 React-pdf 來產生 PDF ](https://hackmd.io/NMxzkKpZTYesoSm6c6qYQw?view) ，稍微修改一點點地方，還算可以。小任務有執行～最近想追加寫晨間日記。

**2. Yunei:**
* 有喔，為了應付金魚腦的我，只好強迫懶惰的我無論如何都要附上，不然做了筆記看不懂都是白費阿...這是我的[筆記](https://hackmd.io/uxbr4hAbRhCv88KG_8ucdw)。
* 已用小目標開啟這藍色的星期一。

**3. Gui:** 有的，基本上一定或多或少都會加上一些解說，以我這篇文章「[更便利於撰寫與管理 CSS 的工具 - Sass / SCSS，如何使用、編譯？](https://guiblogs.com/css-sass-scss/)」即是。同時也會觀看其它人寫的技術文章，主要是參考如何將文章寫得更容易使人理解。

**4. Jane Lin:**
- [這篇](https://hackmd.io/@as60160/SyLlsv9YO/%2FvzycHqZ9RC-cEpiqEcKrOQ) 應該還可以，其他的陸續修改中。
- 今日 mini 小目標完成： 2/2

**5. 大衛:**
* 我每次都一定要把[code](https://hackmd.io/CyTu6tnyRBSXNBTkjbUGLw)寫上去，不然都會看不懂，但有時候會把所有可能性都寫上去，反而會變得雜亂無章，還在練習怎麼寫得乾淨、清楚。
- 今日mini目標已完成！

**6. Susan:**
1. 檢視活動以來撰寫的筆記中，有寫程式碼，也有寫上流程、使用情境。
2. 今天執行超級mini小目標，還在追趕中

**7. Mao:**
1. 把每日目標縮小中，今日mini目標已完成
2. 在寫容易產生錯誤的地方，都會特意做錯誤示範，讓之後再看到同樣的錯誤時，能更快的解決問題，通靈能力提升

**8. 肉魚:**
1. 回頭一看[筆記](https://hackmd.io/@ZCnote/SJkMmiqCO/%2FknXlBK3aQCa4BiCQwW8ZCQ)有夠混雜的，完全被vivian戳到痛點嗚嗚qq，因為趕著在時間之前趕快把東西弄好，導致沒有好好將來龍去脈寫好，僅用很粗略的敘述或者備註來提醒自己...搞了一個超大坑給自己，需要時間好好補上QAQ
2. 以上每日mini任務有做完的都是強者...我努力趕上中 (汗)

**9. Rain Liao:**
自己都事先照抄別人先打的情境敘述的方式，其實編輯上有點懶得再去打一次，目前只能透過隔行，的註解方式或是在漁法下方著解題是重點。ES6的箭頭函式，沒有解釋的話會讓新手看不太懂。

**10. 阿布:**
1.[二.結構與語意標籤](https://hackmd.io/wfdXlnbySCmpI-kQM5sE1w)有特別交代功能與情境，但有時候會有點頓卡，希望能慢慢進步，讓筆記寫作更行雲流水些。
2.有完成~

**11. WA:**
在"權重分數表"，筆記部分試著描述得更清楚，讓筆記描述更能有頭有尾。
[權重分數表](https://hackmd.io/@Cu_w-PQhSTWp-uFWbfyZSw/SknMv2oRO/%2F%40Cu_w-PQhSTWp-uFWbfyZSw%2FBkMu3pvJK)