The Documentation Myth
The Documentation Myth
http://jamesshore.com/Blog/The-Documentation-Myth.html
很多人, 包括我自己, 都認為文件是必要的. 即使抱怨要寫文件的人,在他們需要文件的時候, 也是希望別人也要寫文件給他們. 所以就很容易會有這樣的迷思出現:
Myth: Documentation is good.
但是作者提醒我們一件事, 那就是要文件背後真正的問題是什麼? 他到底認為有什麼問題? 是程式碼寫的不夠清楚? 還是整個程式架構不夠organized? 還是到底是什麼?
因為有時麼你拿到一堆文件, 你也不見得會看, 有時候還會因為文件寫的不夠系統化, 導致你不易了解. 或者是你要找尋一些東西時, 無法很快從這些眾多的文件中找到答案.
所以大家可能真正要的是什麼? 作者認為大家要的應該是解答. 你之所以需要文件, 通常是你有地方不清楚, 想要知道答案是什麼. 有些人想要知道系統架構是如何運作; 有些人想要知道return code有哪些, 各代表什麼意思. 因此最終大家想要的是解答. 所以作者認為換個角度想, 真正的狀況是什麼:
Reality: Answers are good.
如果我們能越快得到答案, 那將會更好更滿足.
但是大家應該也知道可以回答問題的方式有很多種, 文件只是其中一種. 如果有別的方式也可以知道答案, 那是否每個東西都要文件化, 或是立即要文件化, 那就不一定了.
作者這裡提出四種方法, 可以幫助你盡快找到答案. 越前面越是Agile team所想追求的. 但如果做不到, 那就是回歸到原先要寫文件的地步.
1. Best of all is not having to ask the question
- Code that is so well-named and structured that it needs no comments; software whose use is intuitively obvious; libraries that scream their purpose and method of use from every API call.
- XP advocates this as an ideal to strive for.
- It's hard to achieve, sure. We don't always get there, no. But try, and when you think you need documentation, try again.
2. Next best is being able to ask someone the question and get an answer right away.
- Phone calls and email are okay at this, if the other person responds quickly, but the absolute best in speed and communication quality is having the person right next to you, ready to answer the question.
- It's not a pipe dream(白日夢): that kind of instant response is why agile methods emphasize cross-functional and colocated teams. The productivity gains are amazing.
3. Not as good, but still pretty good, is being able to Google the answer easily.
4. And way, way down at the bottom of the list is "reading through documentation to find the answer."
- Sure, sometimes documentation is beautifully organized, wonderfully written, and a pleasure to read.
- Yeah. The rest of the time, it's, um, not. And the more documentation you have to read before you get the answer, the worse off you are.
- More documentation isn't good; just the opposite.
- The only thing great about sheer weight of information--The Almighty Thud--is the sound it makes.
The Documentation Myth
http://jamesshore.com/Blog/The-Documentation-Myth.html
很多人, 包括我自己, 都認為文件是必要的. 即使抱怨要寫文件的人,在他們需要文件的時候, 也是希望別人也要寫文件給他們. 所以就很容易會有這樣的迷思出現:
Myth: Documentation is good.
但是作者提醒我們一件事, 那就是要文件背後真正的問題是什麼? 他到底認為有什麼問題? 是程式碼寫的不夠清楚? 還是整個程式架構不夠organized? 還是到底是什麼?
因為有時麼你拿到一堆文件, 你也不見得會看, 有時候還會因為文件寫的不夠系統化, 導致你不易了解. 或者是你要找尋一些東西時, 無法很快從這些眾多的文件中找到答案.
所以大家可能真正要的是什麼? 作者認為大家要的應該是解答. 你之所以需要文件, 通常是你有地方不清楚, 想要知道答案是什麼. 有些人想要知道系統架構是如何運作; 有些人想要知道return code有哪些, 各代表什麼意思. 因此最終大家想要的是解答. 所以作者認為換個角度想, 真正的狀況是什麼:
Reality: Answers are good.
如果我們能越快得到答案, 那將會更好更滿足.
但是大家應該也知道可以回答問題的方式有很多種, 文件只是其中一種. 如果有別的方式也可以知道答案, 那是否每個東西都要文件化, 或是立即要文件化, 那就不一定了.
作者這裡提出四種方法, 可以幫助你盡快找到答案. 越前面越是Agile team所想追求的. 但如果做不到, 那就是回歸到原先要寫文件的地步.
1. Best of all is not having to ask the question
- Code that is so well-named and structured that it needs no comments; software whose use is intuitively obvious; libraries that scream their purpose and method of use from every API call.
- XP advocates this as an ideal to strive for.
- It's hard to achieve, sure. We don't always get there, no. But try, and when you think you need documentation, try again.
2. Next best is being able to ask someone the question and get an answer right away.
- Phone calls and email are okay at this, if the other person responds quickly, but the absolute best in speed and communication quality is having the person right next to you, ready to answer the question.
- It's not a pipe dream(白日夢): that kind of instant response is why agile methods emphasize cross-functional and colocated teams. The productivity gains are amazing.
3. Not as good, but still pretty good, is being able to Google the answer easily.
4. And way, way down at the bottom of the list is "reading through documentation to find the answer."
- Sure, sometimes documentation is beautifully organized, wonderfully written, and a pleasure to read.
- Yeah. The rest of the time, it's, um, not. And the more documentation you have to read before you get the answer, the worse off you are.
- More documentation isn't good; just the opposite.
- The only thing great about sheer weight of information--The Almighty Thud--is the sound it makes.
全站熱搜
留言列表
