奇葩！面試因?yàn)槲臋n能力不行被pass!
做一個(gè)有溫度的【互聯(lián)網(wǎng)技術(shù)】學(xué)習(xí)小站，包括但不限于Java、Kotlin、Vue等主流技術(shù)分享。熱血程序員永不服輸，下一個(gè)目標(biāo)：【全?！?。日拱一卒無有盡，功不唐捐終入海，關(guān)注我一起進(jìn)步。
寫文檔重要嗎？
作為一個(gè)程序員，你覺得，寫文檔重要嗎？ 個(gè)人認(rèn)為會(huì)寫文檔，寫好文檔很重要且必要。
以下場景你是否似曾相識(shí)：
公司大行敏捷開發(fā)，需求急，任務(wù)重，文檔容易忽視。于是出現(xiàn)了以下的對話：
領(lǐng)導(dǎo)：這個(gè)任務(wù)很急，是核心功能。你們先做好設(shè)計(jì)，避免返工。
幾天后：
A：B同學(xué)你好，我的功能依賴你的接口，你的設(shè)計(jì)文檔給我先看看，到時(shí)一起評審；
B：??？！我每天事情很多，忙不過來，我直接口頭跟你說吧，很簡單的。巴啦巴啦...
A: 不行啊，這是核心功能，我們需要留下技術(shù)文檔，評審一下看看方案如何，也是為了以后方便接手的交接。
B:敏捷開發(fā)，太忙了，沒空，直接說吧。你熟悉這個(gè)模塊，一說你就懂了。寫文檔太麻煩了。
A:......（內(nèi)心：你可真是公司好員工）
在我們公司，面試官一定會(huì)考察應(yīng)試同學(xué)的文檔能力。詢問工作中如何做溝通的，回答的方式有很多，有會(huì)議評審、當(dāng)面提問、遠(yuǎn)程會(huì)議等等。
但是面試官想知道，這些溝通方式都是居于文檔做前提的。如果產(chǎn)品經(jīng)理PRD做的好，開發(fā)者測試者一眼能看懂，就會(huì)減少很多重復(fù)確認(rèn)的次數(shù)。技術(shù)人員之間的溝通更是如此。架構(gòu)師和技術(shù)負(fù)責(zé)人的文檔能力要求更不必說。寫好技術(shù)文檔是非常重要的。
為什么呢？
程序員常說的一句話：我最喜歡寫代碼時(shí)不寫注釋，最不喜歡看看別人代碼時(shí)沒有注釋。
沒有文檔比沒有注釋更讓人覺得代碼是一坨垃圾。沒有文檔的項(xiàng)目后來人根本沒法接手維護(hù)，沒有注釋的代碼會(huì)被問候，沒有文檔的項(xiàng)目會(huì)不會(huì)呢？
文檔的作用
知識(shí)共享：技術(shù)人員編寫的文檔可以幫助傳遞和共享關(guān)鍵知識(shí)和信息。它們可以記錄解決問題的方法、項(xiàng)目架構(gòu)、代碼庫結(jié)構(gòu)等。這樣，即使在團(tuán)隊(duì)中有人離開或新成員加入，他們也可以快速了解項(xiàng)目的工作方式。
提高效率：文檔記錄了最佳實(shí)踐、常見錯(cuò)誤和解決方案，可以幫助其他人更快地解決問題。技術(shù)人員可以編寫教程、指南和示例，以便其他人可以在需要時(shí)參考和使用。
溝通和協(xié)作：文檔促進(jìn)團(tuán)隊(duì)成員之間的溝通和協(xié)作。通過編寫清晰的文檔，技術(shù)人員可以更好地傳達(dá)他們的想法、設(shè)計(jì)決策和項(xiàng)目要求。這有助于減少誤解和提高團(tuán)隊(duì)的工作效率。
維護(hù)性和可維護(hù)性：文檔可以幫助技術(shù)人員更好地理解和維護(hù)代碼。它們可以包括關(guān)于代碼結(jié)構(gòu)、函數(shù)和類的描述，以及對代碼中復(fù)雜部分的解釋。這樣，即使在未來修改或優(yōu)化代碼時(shí)，技術(shù)人員也能夠更容易地理解和維護(hù)它。
知識(shí)管理：文檔是知識(shí)管理的一種方式。它們可以成為組織中的寶貴資產(chǎn)，記錄和保存組織的技術(shù)知識(shí)和經(jīng)驗(yàn)。這樣，組織可以積累并傳承知識(shí)，避免重復(fù)工作，并在需要時(shí)進(jìn)行參考。
總之，技術(shù)人員編寫文檔對于項(xiàng)目的成功和團(tuán)隊(duì)的協(xié)作非常重要。它們有助于知識(shí)共享、提高效率、促進(jìn)溝通和協(xié)作，并支持代碼的維護(hù)性和可維護(hù)性。
如何寫好文檔
好的文檔需要長篇大論嗎？
不需要，追求同事花最少得時(shí)間理解你的描述，多用圖：時(shí)序圖、流程圖、架構(gòu)圖等，一眼能看懂你的表達(dá)。
以下是一些寫好技術(shù)文檔的技巧：
明確目標(biāo)受眾：了解您的目標(biāo)受眾是撰寫技術(shù)文檔的關(guān)鍵。確定讀者的技術(shù)水平和背景，并相應(yīng)地選擇適當(dāng)?shù)恼Z言和內(nèi)容層次結(jié)構(gòu)。根據(jù)讀者的需求和背景，提供足夠的上下文和解釋。給技術(shù)看的技術(shù)文檔，給用戶看的操作手冊區(qū)別很大的。
清晰的結(jié)構(gòu)：確保您的文檔結(jié)構(gòu)清晰且有層次。使用標(biāo)題、子標(biāo)題、段落和列表等來組織信息?？紤]使用目錄或?qū)Ш綆椭x者快速瀏覽和定位所需的內(nèi)容。
清晰簡潔的語言：使用簡潔明了的語言表達(dá)技術(shù)概念，避免使用過于專業(yè)化的術(shù)語和縮寫（統(tǒng)一語義）。使用簡單的句子和段落，并避免冗長的句子。
提供示例和代碼片段：示例代碼是理解技術(shù)概念和實(shí)現(xiàn)的重要工具。提供清晰、簡潔的示例代碼，并解釋關(guān)鍵部分的工作原理和用途。確保示例代碼可供讀者直接使用和測試。
圖表和圖形化表示：使用圖表、圖形和圖像來輔助解釋和展示技術(shù)概念。圖表可以幫助讀者更好地理解流程、架構(gòu)和關(guān)系。確保圖表清晰、簡潔，并提供必要的標(biāo)注和解釋。
引用和鏈接：在文檔中引用其他相關(guān)文檔、資源或參考資料。提供鏈接或引用，使讀者可以進(jìn)一步查閱相關(guān)信息。確保鏈接有效，并在文檔中提供足夠的上下文，以便讀者理解鏈接的內(nèi)容。
更新和維護(hù)：技術(shù)文檔應(yīng)該與項(xiàng)目的發(fā)展保持同步。要求同步修改。
使用合適的工具：選擇適合您的需求的文檔撰寫工具。這些工具可以提供格式化選項(xiàng)、版本控制、團(tuán)隊(duì)協(xié)作和導(dǎo)出為不同格式的功能。一些常用的技術(shù)文檔工具包括Markdown、PlanUML等。工具用來提高生產(chǎn)效率，比如代碼畫圖而不是用在線工具拖拉調(diào)整費(fèi)時(shí)，我們不需要追求美觀。
自己怎么進(jìn)步文檔寫作能力？
學(xué)習(xí)MarkDown、PlanUML等工具的基本使用。
自己多做筆記和總結(jié)，溫故知新?？梢宰约号獋€(gè)博客/公眾號(hào)/做個(gè)自己的文檔庫等。用來管理或分享自己的總結(jié)，強(qiáng)迫自己去動(dòng)手寫。
“借鑒”優(yōu)秀的文檔，多做多練。
對自己的文檔要求嚴(yán)格，長期積累有益無害。我入職這家公司，因?yàn)槲易约浩綍r(shí)寫公眾號(hào)的文章，加了不少分。
文檔先行，做需求，先把文檔做好，文檔做完，整個(gè)流程和思路已經(jīng)了然于胸，寫代碼可以避免返工，更高效。
做一個(gè)有溫度的【互聯(lián)網(wǎng)技術(shù)】學(xué)習(xí)小站，包括但不限于Java、Kotlin、Vue等主流技術(shù)分享。熱血程序員永不服輸，下一個(gè)目標(biāo)：【全?！俊Ｈ展耙蛔錈o有盡，功不唐捐終入海，關(guān)注我一起進(jìn)步。
