建站
咨詢
售后
建站咨詢
新聞中心
成功和可持續(xù)的項(xiàng)目，與那些消失無蹤的項(xiàng)目有什么不同？答案是 —— 社區(qū)。社區(qū)是開源項(xiàng)目的發(fā)展動(dòng)力，而文檔是構(gòu)建社區(qū)的基石之一。也就是說，文檔的意義不僅僅在于文檔本身。
10多年的班瑪網(wǎng)站建設(shè)經(jīng)驗(yàn)，針對設(shè)計(jì)、前端、開發(fā)、售后、文案、推廣等六對一服務(wù)，響應(yīng)快，48小時(shí)及時(shí)工作處理。全網(wǎng)營銷推廣的優(yōu)勢是能夠根據(jù)用戶設(shè)備顯示端的尺寸不同，自動(dòng)調(diào)整班瑪建站的顯示方式，使網(wǎng)站能夠適用不同顯示終端，在瀏覽器中調(diào)整網(wǎng)站的寬度，無論在任何一種瀏覽器上瀏覽網(wǎng)站，都能展現(xiàn)優(yōu)雅布局與設(shè)計(jì)，從而大程度地提升瀏覽體驗(yàn)。創(chuàng)新互聯(lián)從事“班瑪網(wǎng)站設(shè)計(jì)”,“班瑪網(wǎng)站推廣”以來，每個(gè)客戶項(xiàng)目都認(rèn)真落實(shí)執(zhí)行。
建立好的文檔可能很困難。用戶不愿意閱讀文檔，因?yàn)樗灰撞檎?，它很快就過時(shí)了，它冗長，或者它不全面。
開發(fā)團(tuán)隊(duì)不寫文檔，因?yàn)樗麄兿萑肓恕皩ξ襾碚f顯而易見，所以對所有人都顯而易見”的陷阱。他們不寫，因?yàn)樗麄兠τ陂_發(fā)項(xiàng)目。要么是需求變化太快了，要么是開發(fā)得還不夠快。
但是好的文檔仍然是團(tuán)隊(duì)和項(xiàng)目之間最好的溝通工具。考慮到項(xiàng)目隨著時(shí)間的推移往往會(huì)變得更大，這一點(diǎn)尤其重要。
文檔可以是團(tuán)隊(duì)或公司內(nèi)部的唯一真理。這在協(xié)調(diào)人們朝著共同的目標(biāo)前進(jìn)，以及在人們轉(zhuǎn)移到不同的項(xiàng)目時(shí)保留知識方面非常重要。
那么，要如何為一個(gè)項(xiàng)目寫出合適的文檔，并與正確的人分享呢？
什么是成功的社區(qū)文檔？
要想在你的社區(qū)文檔編寫中取得成功，你需要：
- 規(guī)劃你的路徑
- 使其清晰簡單
- 靈活變通，根據(jù)具體情況調(diào)整路徑
- 做版本控制
圖片展示了建立文檔的整個(gè)流程
靈活并不意味著混亂。許多項(xiàng)目之所以成功，就是因?yàn)樗鼈兘M織得很好。
James Clear（《原子習(xí)慣Atomic Habits》一書的作者）寫道：“你并不是提升到了你目標(biāo)所在的水平，而是降低到你整個(gè)系統(tǒng)所在的水平?！币欢ㄒM織好過程，使水平足夠高，才能取得成功。
設(shè)計(jì)流程
文檔本身就是一個(gè)項(xiàng)目。你可以把寫文檔當(dāng)作寫代碼一樣。事實(shí)上，文檔可以是一個(gè)產(chǎn)品，而且是一個(gè)非常有價(jià)值的產(chǎn)品。
這就意味著你可以采用與軟件開發(fā)相同的流程：分析、獲取需求、設(shè)計(jì)、實(shí)現(xiàn)和維護(hù)，把文檔作為你的一個(gè)流程對待。
在設(shè)計(jì)流程時(shí)，要從不同的角度考慮。不是所有的文檔都適用于所有人。
大多數(shù)用戶只需要一個(gè)了解項(xiàng)目概況的文檔，而 API 文檔則是留給開發(fā)者或高級用戶的。
開發(fā)者需要了解庫和函數(shù)的文檔。用戶則更需要看到示例、操作指南，和項(xiàng)目與其他軟件相配合的架構(gòu)概述。
圖片展示了編寫文檔時(shí)的不同視角
總之，在創(chuàng)建任何流程之前，你必須確定你需要什么：
- 關(guān)注的群體： 包括開發(fā)者、集成商、管理員、用戶、銷售、運(yùn)營、高管
- 專業(yè)水平： 要考慮到初級、中級和高級用戶
- 詳細(xì)程度： 既要有高層級的概述，也要有技術(shù)細(xì)節(jié)，所以要考慮如何呈現(xiàn)這些內(nèi)容
- 路徑和入口： 人們?nèi)绾握业轿臋n，如何使用文檔
當(dāng)你思考這些問題時(shí)，它可以幫助你構(gòu)建你想通過文檔傳達(dá)的信息的結(jié)構(gòu)。它定義了文檔中必須包含的內(nèi)容的清晰指標(biāo)。
下面是如何圍繞文檔建立一個(gè)流程的方法。
編碼約定
代碼本身應(yīng)該有意義。文檔應(yīng)通過良好的類名、文件名等來表達(dá)出來。通過思考以下內(nèi)容，創(chuàng)建通用的編碼標(biāo)準(zhǔn)和自我注解的編碼過程：
- 變量命名約定
- 通過使用類、函數(shù)命名方案使名稱易于理解
- 避免深度嵌套，或 ??根本不嵌套??
- 不要簡單地復(fù)制和粘貼代碼
- 不應(yīng)使用長方法
- 避免使用幻數(shù)（改用常量）
- 使用提取的方法、變量等
- 使用有意義的目錄結(jié)構(gòu)、模塊、包和文件名
開發(fā)時(shí)測試
測試不僅僅是關(guān)于代碼應(yīng)該如何工作。它還涉及如何使用 API、函數(shù)、方法等。編寫良好的測試可以揭示基本用例和邊緣用例。甚至還有一種 ??測試驅(qū)動(dòng)開發(fā)?? 的實(shí)踐，專注于在代碼開發(fā)之前創(chuàng)建測試用例（應(yīng)該測試什么以及如何測試的分步場景）。
版本控制
版本控制（即使是對文檔進(jìn)行版本控制）可以幫助你跟蹤更改的邏輯。它可以幫助你回答為什么這么修改。
確保提交期間的注釋能解釋為什么進(jìn)行更改，而不是進(jìn)行了哪些更改。
編寫文檔過程越吸引人，就會(huì)有更多的人參與其中，為它添加創(chuàng)造力和樂趣。你應(yīng)該通過以下方式考慮文檔的可讀性：
- 軟件代碼約定
- 圖表和圖形（也通過文字進(jìn)行解釋）
- 思維導(dǎo)圖
- 概念圖
- 信息圖表
- 圖片（突出顯示重要的部分）
- 短視頻
通過使用不同的交流方式，你可以提供更多的方式來參與文檔。這有助于防止誤解（不同的語言，不同的含義）和有助于通過不同的學(xué)習(xí)方式進(jìn)行學(xué)習(xí)。
以下是一些用于創(chuàng)建文檔的軟件工具：
- Javadoc、Doxygen、JsDoc 等： 許多語言都有自動(dòng)化的文檔工具，以幫助捕獲代碼中的主要功能
- Web 鉤子和 CI/CD 引擎： 允許持續(xù)發(fā)布文檔
- Restructured Text、Markdown、Asciidoc： 文件格式和處理引擎，幫助你從純文本文件中生成美觀且實(shí)用的文檔
- ReadTheDocs： 是一個(gè)可以和公共 Git 存儲(chǔ)庫聯(lián)動(dòng)的文檔托管主機(jī)
- ??Draw.io???、LibreOffice Draw、Dia： 制作圖表、圖形、思維導(dǎo)圖、路線圖、計(jì)劃、標(biāo)準(zhǔn)和指標(biāo)等
- Peek、Asciinema： 記錄終端命令操作
- VokoscreenNG： 錄制屏幕和鼠標(biāo)點(diǎn)擊操作
文檔很重要
編寫文檔的過程和協(xié)議與項(xiàng)目本身同樣重要。最重要的是，它把項(xiàng)目的信息和項(xiàng)目的創(chuàng)造傳達(dá)到位，更加令人興奮。
快速進(jìn)入項(xiàng)目和流程，以及了解一切是如何工作的，是文檔一個(gè)重要的功能。它有助于確保眾人持續(xù)參與。通過在團(tuán)隊(duì)中構(gòu)建一種“語言”，可以簡化流程，更清晰地理解所要做的事情。
文檔旨在傳達(dá)價(jià)值，即無論是通過團(tuán)隊(duì)成員還是通過應(yīng)用程序的用戶的言行，來展示出某些東西。
要將這個(gè)過程視為一個(gè)連續(xù)的整體，并在其中融合使用溝通、流程和文檔的方式。
圖片展示了文檔作為一種溝通的過程
文檔是一種溝通手段。
（題圖：MJ:document development illustration in high resolution, very detailed）
分享文章：編寫對社區(qū)真正有用的文檔
當(dāng)前地址：http://www.dlmjj.cn/article/cdhcehc.html
