如何理解寫文檔這件事情 ?

目錄

目錄

前言

對公司而言

標準化流程

最佳實踐

對自己而言

前言

個人札記, 寫下對 寫文檔 這件事情的理解, 歡迎討論.

對公司而言

文檔系統是 標準化流程 和 最佳實踐 的溫床. 我們不僅是在編寫文檔, 更是在打造一個屬于公司的文檔系統.

標準化流程

在大部分企業的發展進程中, 都需要孵化出屬于自己的一套 SOP(標準化操作流程), 完善的 SOP 最終會覆蓋到企業所有業務流程. 例如: 開發團隊業務中的 標準化開發流程, 標準化開發環境, 標準化代碼編寫, 標準化注釋與代碼文檔生成 等.

為什么需要標準化?

這個問題類似于 為什么需要規范的代碼風格? 規范代碼風格的實踐意義在于讓團隊的合作更加無縫, 讓代碼的承接更加流暢. 而 SOP 蘊含了更大的意義, 其能帶來諸如: 降低公司規模擴大所帶來的阻塞感, 讓公司的管理細節更加透明, 由體制和流程來調度員工, 降低對人的依賴 等好處. 總的來說, 就是打造一個中心, 讓所有人都圍著它轉, 這樣才能夠提高向心力和執行力. 公司的每一位成員都是標準的制定者, 同時也標準的執行者.

如何實現 SOP?

由外部引入

好處: 有參考案例

壞處: 兼容度不確定

從內部總結

好處: 契合自身實際

壞處: 需要長時間的積累

顯然, 后者所總結出來的 SOP 會更加健壯, 而總結的載體就是文檔系統.

最佳實踐

最佳實踐可以理解為最優的問題解決方案, 是在不斷實踐的基礎上作出的經驗性結論.

如何讓每一次實踐都更具價值?

共享: 讓所有人都能收獲經驗值

集思廣益: 問題的拋出應該要像打漁撒網一般, 更廣的受面意味著更多的可能, 網聚人的力量.

“實踐-總結” 的循環迭代: 這同樣需要一個載體去承托實踐的思路, 并在此基礎上不斷打磨, 優化.

所以, 文檔系統能夠讓閃現的靈光得以持久化保存, 而不讓它消散在討論聲之中.

對自己而言

培養自身表達能力和嚴謹邏輯思維的方法論.

寫文檔和寫代碼本質上是一樣的, 都是語言的組織和思想的傳遞行為. 有科學數據表明, 善于寫文檔的程序員所寫的代碼會更加優雅. 因為 結構層次是否分明? 措辭選詞是否精準? 科學邏輯是否嚴謹? 概念定義是否高度抽象? 這些優秀論文的標準, 也同樣是優秀代碼的標準.

在我們寫代碼的大多數時間里, 其實都是潛在意識在控制自己, 而我們的主觀主觀意識. 例如:

使用 print 語句還是 print() 函數?

使用 not in 還是 in ?

使用 for-else 還是 for-跳出縮進 ?

使用 if in 還是 if not in ?

當在使用上述兩者都能夠實現相同 結果 的情況下, 你會如何選擇? 很可能是由潛在意識, 也就是我們的個人習慣來決定的. 但對于經驗豐富的程序員而言, 在選擇的時候就可能會考慮到 Python2 和 Python3 的兼容性的問題, 可讀性的問題, Pythonic 的問題, 邏輯性完整的問題. 所以:

潛在意識 > 主觀意識 ==> 菜鳥 主觀意識 > 潛在意識 ==> 老炮

1

2

寫文檔相比于寫代碼更能培養上述的技術素養, 因為前者不會受到字符串的視覺擾亂和英文語境的阻礙, 更能專注于 思路的完善和擴展.

所以, 當你認為自身的表達能力有所欠缺時, 開始寫點東西吧.

開發者

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。