[工作日誌] #2 談談撰寫文件
結論
文件能不能解決問題？
某些目的和用途上能提供的幫助非常有限，在我全程主持的幾個專案，努力要求了，了解了某些事情，最終釋懷了些一直堅持的想法。
放下別人的要求，繼續堅持認為該做的事務。
以文件為主軸，在部門的環境內這個方法行不通，因為我們頭痛的問題與面臨的狀況，文件並沒有太有效與即時的助益。
文件在開發上的好
開發的過程中，文件可以很有邏輯條列規格，多人開發、前後端溝通上大幅地減少溝通落差，這點非常有幫助。
在文件幾乎齊備的情況下，就不太會發生以下情形
1. 多人開發上互相介接，介接上有嚴重錯誤或誤會。 2. 進乎成品後才發現團隊有功能漏做，以為有人會實現缺少的部分。 3. 需求不明確，送測或上線後才發現。 4. 上線後發現系統不穩定，因為未在設計階段做考量，後續難以補救。
文件不能有效地解決，目前往往遇到的瓶頸問題，不過帶來的好處某方面來說，依舊難以取代。
我認為文件是製作好專案一個必要的環節，所以都會做文件，也一直嘗試做出每個專案最適合的文件。
一直以來也不斷鍛鍊自己撰寫文件，畫各種說明圖的技巧，這部分在有限的成本與考量上能做的已經趨於極致。
需求文件，SA，SE，SD，DB規格，API規格，Redis規格，專案注意事項，有限的壓力測試說明與報告，流程圖，架構圖，河道圖，有序圖，FSM，看專案用什麼表達可以最清楚關鍵重點，持續以來的自我要求，好像達到某種程度或者說是自己的極限，以2/8法則來說，要再更精進，需要再花費80%的精力才有20%進步，何必呢？文件只是一種工具。
一路走來
目前本分是工程師，做著工程師的工作，理所當然對於寫文件也難相比設計程式上的幹勁，只不過是必須的部分，對此報以敬業的態度一直在努力。
自己好像太過一廂情願的往前跑，情境好比抵達里程碑後停下腳步環顧四周，才驚覺沒人跟上(不知道是不想跟我著我的方向走，還是跟不上)，除了自己的腳印只有荒煙漫草，不見他人人影。
不是我在的專案，文件不文件的，撰寫文件的推廣上，逐漸感到意興闌珊。
他們需要的不是文件。
也許大部分人很難理解文件內容描述背後的意義。
很多人未俱備契約精神，定好的規格，沒那麼嚴格考慮或遵守。
過往經驗，重視文件的起點
不知不覺，回過神來，我也沒想到現在的自己對於文件的理解上，在部門內已經與很多人不同。
當初前公司的老大教畫圖，持續的教學相長，講解為什麼接金流該畫什麼圖，什麼是系統狀態流程規劃，為什麼一開始就要確認好哪些部分是1對1，1對多，還是多對多.......
當下懵懵懂懂地強行記下了，但理解有限。
看到前老大接過別家的系統，就憑著DB規格文件，就可以兜出系統大概怎麼跑，分析給我示範那瞬間，大概觸動了心裡某一塊靈魂。
以前有類似的經驗，建築系的教授，在我面前看著一張牆壁的照片，就可以跟助教講解結構與材質甚至某些情況也可以推測得知(當時在幫他們做網站)。
拍照片的人知道要拍什麼，看照片的人知道要看什麼，專業對專業，外行人一點都不明白。
這大概就是我的動力
大抵上設定以下這幾個面向，我一直想盡辦法努力著，做出最適合的文件。
1. 為什麼要做這個文件 2. 想讓別人了解什麼 3. 為什麼要這樣畫，為什麼要這樣寫 4. 怎麼形容或表達每一塊的關係
每次告訴自己，人家不看你的文件是不是做得不夠好，是不是有更好的敘述方式，能夠更簡潔的表示專案的核心內容。
然而堅持這種想法以來，結果除了好像有鍛鍊到自己某種技能，對環境起不到什麼浪花。
我自己改變了，然後環境呢？別人呢？
也許有人不認可我的作法，也許有人心理覺得我寫出來的文件其實跟屎一樣，我覺得沒關係。
人都無法強迫別人的喜好和認可，但我覺得方向對就......堅持吧！
觀察、思考、分析
自從有意識的推團隊用文件的方式為開發的工具，到覺得此法不可行，前後大約兩年，兩年過去了沒用就是沒用，若不果斷放棄，難道還認為有天突然大家都明白什麼了嗎？
到這一步，我能做的是思考這段期間以來的困境，試圖尋找或設想其他方法克服推文件的困難點，改變團隊駐足不前的現狀。
用自己的角度分析了難以實現的原因。
1. 我的角色好像在賣產品，我賣得不夠好，講得不夠誘人，拜託以現實實務方面，若不自己覺得有需求，怎麼會有興趣聽你講得口飛橫沫，所以賣得很失敗。
也是我從來不把撰寫文件當產品來跟大家推銷，直覺來說，一直比較像是技術或經驗分享，不會搞得好像在直銷一樣，營造現在不買錯過可惜，努力撰作文件的話專案就會很厲害，
考試都考一百分，也許有機會，我應該舉很多因為寫文件，而成功的案例？
明顯寫文件是無聊的，要付出成本的，互相看彼此的文件可能是有誤解的，甚至有批評的，沒了解好處之前，成本就擺在眼前。
2. 我觀察部門裡，很少人在開發新專案，會檢討前面的專案的設計缺陷做為經驗，改善下個專案，新工作來好像只是換實做不同的業務在碰運氣。
換句話說，基本上根本沒人會去翻之前專案的設計文件，其它人有沒有設計文件我還很懷疑，除了API文件好像比較被廣泛接受，其他的ㄧ點都不重視。
3. 可能非客觀地嚴重懷疑，蠻多人根本就看不懂作圖要表達的重點，為什麼是畫河道圖？叫你看哪有不同角色，到他那邊該做什麼處理。
為什麼是畫有序圖？作業上的順序是這個系統的重點，你要考量哪邊斷了要怎麼處理。
為什麼畫FSM？這個專案的狀態演化和轉換複雜，幫助你知道你身處在哪個狀態，是怎麼來著，又會怎麼演變。
我受不了一堆人看圖講出的話非常外行，我畫這些除了自己確認派得上用場以外，到底要幹嘛？
4. 大家都很忙，沒時間看文件。假設文件真的很完整很詳細，有些專案實在很難你只花個10分鐘~半小時就能看懂在做什麼，要考量什麼，大家有心理準備付出十足的精神用一段時間試圖理解文件內容嗎？
一分兩份到十份我自己就不願意，我的大部分工做在開發，而不是精讀可能ㄧ年內都用不上的文件，尤其當中有牽扯到複雜的設定和計算的時候，理解需求就夠吃一壺了吧，要思考吸收消化的速度和程度真的是見仁見智。
想想大學課本一個lesson看了半小時，就能考試作答了嗎？用經濟學的角度解釋，明擺的大成本要你先付出，卻不一定後續有收益，所以事情很好解釋吧。
5. 功能一直出，開發人員怎麼可能熟悉每個文件和專案內容，大大小小在線上的功能，20 30個跑不掉吧，更多是我不知道的，即使每個人開發都有寫文件，平常不怎麼碰過，難道文件內容和功能說明要背下來嗎？即使背了能撐多久？半年？一年？
就我開發的專案來說，半年前在會議桌上配合文件說明跟大家講的注意事項，看各位基本上現在都忘了，這是不可行的，過去別人的專案講解，到現在我也幾乎忘一乾二淨。
6. 文件在開發完成後，到底能做什麼用途，除了以下幾點我不認為有什麼動機讓人會特別回顧文件，以這些目的我會去翻文件，其他人的想法就不知道了。
1. 思考架構設計作檢討。
2. 核對規格，不論是需求，環境，程式變數，程式規格，都很好用。
3. review複雜不直覺的需求。
7. 部門的問題，有部分是想藉由文件的方式，在收到緊急的狀況處理，程式或資料嚴重錯誤，有個參考或問題排除依據。
緊急狀況？資料出錯？靠文件知道要怎麼排除或處理？由於部門一直以來都是這個方式作業，我也沒想太多的ㄧ直跟著這樣做到今年初。
很不對勁吧，上線很久的東西會突然有問題？那為什麼之前沒問題？為什麼會有這樣的情況，來來去去我整理出了5個種類。
1. 最輕微：程式設計未考量周全，或需求的業務邏即有互相牴觸，顯示方面或功能有個體會在某個特定狀況出現瑕疵‧
2. 可能中等或嚴重：系統遇到了極端狀況，超乎當初設計與評估。
3. 非常嚴重：資料來源拿不到，中間不通，我們的服務處理又要求處理必定成功。
4. 嚴重到引起連鎖效應：錯誤的資料提供，一層pass一層，像病毒一樣，發作時幾乎已經攻佔大半江山，如瘟疫散佈了某個範圍。
5. 非常嚴重：設備問題，一開始系統就全掛了，或者入口掛了還好辦。若引發第3或第4點類型的狀況，要求必定成功的請求，中間卻因設備連線或出狀況失敗，提供資料或要求資料時有時無，造成不齊全的資料引起的資料錯誤，根本災難製造源。
第一點，問題沒話說，就該死有bug，思慮有缺又剛好測試案例沒測到，應該補測試與測試報告，設計上為什麼被忽略檢討作為經驗，這部分的傳承，我一直覺得若能寫成文件分享ㄧ定很棒。
第二點，維運人員的確很難第一時間判斷出問題原因，即便開發者也很困難。文件可以某種程度上的幫助大家確認程式設計架構，分析極端狀況的發生起源或範圍。
但這種案例往往更考驗個人經驗，首先要找出遇到「什麼極端」是最困難的事情，知道狀況了，後續處理就不在話下。
第三點，找error log 應該最快？不干文件事情。
第四點，除了有花費功夫事先準備好的測試物件和預期結果，還有準備到每階段的驗證，不然只有問題發生了想辦法人工驗證，除此之外沒其他辦法，也不干文件事情。。
第五點，叫管設備的出來面對，文件能做什麼？
8. [問題集的理想鄉]，想來想去，我覺得最適合這樣形容。什麼叫問題集？我的理解釋有著目錄或者索引可以快速提供查詢。
這件事我覺得非常莫名其妙，送測後，上線後，還有問題，你才會想列到上面吧，你不會把送測時發現的問題，已經修正了，還列到這裡來，測試報告才是它的歸處。
如果是發生過的問題，為什麼之後還有可能發生，那麼修正的人，與測試的人到底在幹嘛，要嘛後來的問題是新問題，只是表像一樣而已，錯誤原因不同，要嘛就是修正的人對當出問題發生原因理解不夠徹底，所以沒修好。
所以正常來講，發生過的問題不該也不會再發生，想列這個問題在文件，用處是我覺得是上面7-1點的部分，而非提供發生問題後可以拿來幫助參考。
那列出[可能會發生]的問題？覺得可能為什麼不事先測，有可能發生問題還敢上線，要不以我的專案複雜度蠻高的來說，debug工具跑下去前前後後可以整理出30個變數在控制或說明程式運行狀態，
假設每個變數只表示true/false好了，2的30次方種可能，你怎麼寫說當你遇到第一個變數是true，第二個是false，第三個是true...是哪邊有問題，哪邊可能資料對不上，條列式說明2的30次方種狀況可能你怎麼寫。
所以我認為憑空設想的假設問題集是講好聽的。
一直以來，部門會列這種問題集，我的觀察不外乎兩種。
1. 根本不是問題，第一線客服人員對需求或程式功能不理解，覺得是問題，或者發生狀況、手邊可拿到的表象資訊讓他無法判斷，所以來問來煩，開發人員要應付這個我覺得是蠻怪的，或者我有誤會什麼，我們本來就不是單純的開發人員。
2. 問題一直重複發生，那為什麼我們自己不解決？根本問題的根源不在我們這邊要怎麼解決？提供資料的部門，設備的部門，災難往後傳，他們不能保證能解決什麼問題，能不再同樣事情發生，我們卻要保證什麼。
所以要事先準備，諸位前科在案，我們有備案記錄，問題發生先拿備案記錄查詢？開發人員，或者善後災難的開發人員，要負責寫這個......文件？
反思了一下，也許部門對於[文件]的認識，已經淪於疲於應付現實狀況處理的病態工具，跟我的認識認知不同，我了解的好......其他人不懂情有可原。
後續
我們遇到的問題是殘酷的，現實的，但文件已經幫不上忙，了解狀況後，應該嘗試採用其他方法，面對我們的問題。
留言
張貼留言