Python 實時聊天室搭建：發(fā)布訂閱頻道API實戰(zhàn)應(yīng)用
SDLC不同階段的項目文檔
技術(shù)文檔解釋了產(chǎn)品功能，幫助設(shè)計項目活動，并明確了最終目標(biāo)。
有些人認(rèn)為技術(shù)文檔只是為開發(fā)團(tuán)隊創(chuàng)建的，但這并不完全正確。雖然它確實包含了大量的技術(shù)信息，但它實際上可以幫助不同的涉眾小組達(dá)成一致，并共享對預(yù)期結(jié)果的共同理解。此外，正如我們將進(jìn)一步解釋的那樣，不同類型的文檔是為不同的受眾創(chuàng)建的——有時，不是技術(shù)專家(例如，最終用戶指南)。
團(tuán)隊生成的文檔類型及其范圍取決于所選擇的軟件開發(fā)方法。主要有兩種:敏捷和瀑布。就附帶的技術(shù)文檔而言，每個都是唯一的。
瀑布式方法是一種線性方法，在這種方法中，你只有在完成前一個階段后才能進(jìn)入下一個階段。在項目的早期階段，使用瀑布法的團(tuán)隊在產(chǎn)品規(guī)劃上花費(fèi)了相當(dāng)多的時間。它們創(chuàng)建了主要目標(biāo)和目的的廣泛概述，并詳細(xì)計劃了工作過程的外觀。
瀑布方法階段
瀑布團(tuán)隊努力在任何工程階段開始之前編寫詳細(xì)的文檔。仔細(xì)的計劃對于進(jìn)度幾乎沒有變化的項目非常有效，因為它允許精確的預(yù)算和時間估計。然而，瀑布計劃對于長期開發(fā)是無效的，因為它沒有考慮到可能發(fā)生的變化和突發(fā)事件。
敏捷式方法基于團(tuán)隊合作、開發(fā)人員、業(yè)務(wù)涉眾和最終客戶之間的密切協(xié)作、靈活性和快速響應(yīng)更改的能力。敏捷開發(fā)的基本構(gòu)建模塊是迭代:每個迭代都包括計劃、設(shè)計、開發(fā)等階段。
敏捷開發(fā)周期
敏捷方法在開始時不需要全面的文檔。經(jīng)理不需要提前計劃太多，因為隨著項目的發(fā)展，事情會發(fā)生變化。這允許進(jìn)行及時的計劃。
敏捷宣言的價值之一是“工作軟件勝過全面的文檔”。雖然敏捷更關(guān)注產(chǎn)品本身，但形式也不應(yīng)該被忽視。因此，我們的想法是生成包含信息的文檔，這些信息對于在最有意義的時候向前推進(jìn)至關(guān)重要。
今天，敏捷是軟件開發(fā)中最常見的實踐:根據(jù)第17次敏捷狀態(tài)報告，71%的公司在他們的SDLC中使用它。因此，我們將重點(diǎn)關(guān)注與此方法相關(guān)的文檔實踐。
有效文檔的主要目標(biāo)是確保開發(fā)人員和其他涉眾一起工作來完成項目的目標(biāo)。存在不同的軟件文檔類型來實現(xiàn)這一目標(biāo)。
敏捷項目中最常用的軟件文檔
所有軟件文檔可以分為兩大類:
產(chǎn)品文檔描述了正在開發(fā)的解決方案，并提供了如何與之交互的說明。一般來說，產(chǎn)品文檔包括需求、技術(shù)規(guī)范、業(yè)務(wù)邏輯和手冊。產(chǎn)品文檔主要有兩種類型:
過程文檔描述了團(tuán)隊在開發(fā)軟件時如何工作。它就像一本詳細(xì)的指南，列出了團(tuán)隊成員在SDLC期間遵循的過程，他們使用的工具，以及他們必須遵守的規(guī)則。該文檔幫助每個人理解如何完成任務(wù)，并使步驟一致，以方便新的團(tuán)隊成員更容易跟上進(jìn)度。
與過程文檔相關(guān)的常見示例是待辦事項、路線圖、編碼和測試標(biāo)準(zhǔn)、報告、會議記錄、發(fā)布檢查表，甚至業(yè)務(wù)通信。
因此，讓我們更詳細(xì)地討論每個文檔類別。
系統(tǒng)文檔提供了解決方案的概述，并幫助工程師和涉眾理解底層技術(shù)。它通常包括
值得強(qiáng)調(diào)的是，這個列表并不詳盡。讓我們檢查一下主要的系統(tǒng)文檔。
產(chǎn)品需求文檔或PRD提供有關(guān)系統(tǒng)功能和行為的信息。一般來說，需求是關(guān)于系統(tǒng)應(yīng)該做什么以及它應(yīng)該如何工作的陳述。
一個合理的做法是使用所有團(tuán)隊成員都遵守的單一的、一致的模板來編寫需求文檔。單一網(wǎng)頁的表格有助你保持文件簡潔，并節(jié)省查閱資料的時間。下面是一個單網(wǎng)頁P(yáng)RD的示例，以了解其各種元素。但是，請記住，這不是編譯它的唯一方法。
技術(shù)文檔示例:使用內(nèi)容協(xié)作軟件Atlassian Confluence創(chuàng)建的一個網(wǎng)頁軟件需求文檔
以下是產(chǎn)品需求文檔中需要包含的要點(diǎn)。
角色和職責(zé)。從項目參與者的信息開始，包括產(chǎn)品所有者、團(tuán)隊成員和其他關(guān)鍵涉眾。這些細(xì)節(jié)將明確每個團(tuán)隊成員的職責(zé)和角色。
團(tuán)隊目標(biāo)和業(yè)務(wù)目標(biāo)。簡要地定義項目最重要的目標(biāo)。
背景和戰(zhàn)略契合。對你的行動的戰(zhàn)略目標(biāo)做一個簡短的解釋。你為什么要開發(fā)這個產(chǎn)品?它將如何與公司的目標(biāo)保持一致?什么是市場契合度?
假設(shè)。創(chuàng)建一個您計劃在項目期間驗證或取消的技術(shù)或業(yè)務(wù)假設(shè)的列表。
用戶故事。列出或鏈接項目所需的用戶描述。從最終用戶的角度出發(fā)，用戶故事是對客戶行為和他們想要達(dá)到的結(jié)果的簡短描述。
驗收標(biāo)準(zhǔn)。這些是指示用戶描述完成的條件。驗收標(biāo)準(zhǔn)的主要目的是從最終用戶的角度為交互場景定義一個令人滿意的結(jié)果。
用戶交互和設(shè)計。通常，精確的設(shè)計是在組成PRD之后創(chuàng)建的，因此您可以只包含產(chǎn)品設(shè)計的一般指導(dǎo)或草圖。稍后，當(dāng)實際設(shè)計可用時，您可以將它們鏈接到珠三角。
問題。當(dāng)團(tuán)隊在項目進(jìn)展中解決問題時，他們不可避免地會產(chǎn)生許多問題。一個好的做法是記錄所有這些問題并跟蹤它們。
超出范圍(不合適)。列出你在這個項目中不打算做的事情，以設(shè)定清晰的界限，防止范圍蔓延。這些可以是與產(chǎn)品相關(guān)的功能，但不是作為這個特定項目的一部分開發(fā)的。例如，如果你建立一個電子商務(wù)網(wǎng)站，一個定制的移動應(yīng)用程序可能是一個超出范圍的項目。您還可以在這里指定額外的服務(wù)，如項目后維護(hù)，以明確您的責(zé)任。
請注意，除了PRD之外，其他類型的與需求相關(guān)的文檔是為不同的目的而創(chuàng)建的。最值得注意的是業(yè)務(wù)需求文檔(BRD)和軟件需求規(guī)范(SRS)。簡而言之，它們之間的主要區(qū)別在于BRD側(cè)重于業(yè)務(wù)角度，而PRD從用戶和市場的角度概述產(chǎn)品的需求，而SRS則提供詳細(xì)的技術(shù)藍(lán)圖，說明軟件應(yīng)如何發(fā)揮功能以滿足這些需求。
用戶體驗設(shè)計(UX設(shè)計)從規(guī)劃階段開始，貫穿所有開發(fā)階段，包括測試和發(fā)布后階段。用戶體驗設(shè)計的過程包括研究、原型設(shè)計、可用性測試和實際設(shè)計階段，在這個階段會產(chǎn)生大量的文檔和交付物。
研究階段包括收集有關(guān)用戶以及他們與產(chǎn)品交互的環(huán)境的見解。應(yīng)用的技術(shù)包括用戶訪談、調(diào)查、觀察和市場分析。目標(biāo)是了解用戶的需求、行為、痛點(diǎn)和動機(jī)。它意味著發(fā)展
用戶角色代表了潛在產(chǎn)品用戶的關(guān)鍵特征，關(guān)注于行為、思維模式和動機(jī)。它們有助于定義客戶細(xì)分，為不同的用戶群體定制產(chǎn)品功能和未來的營銷策略。
用戶場景是描述用戶角色為完成特定任務(wù)將采取的步驟的文檔。用戶場景關(guān)注用戶將做什么，而不是概述思維過程。
場景映射用于將現(xiàn)有用戶場景編譯為單個文檔。場景映射顯示了每個功能在給定時刻可用的所有可能場景，以及交叉的場景步驟。
在原型設(shè)計階段，用戶體驗設(shè)計師處理研究階段的交付成果。他們開發(fā)最終產(chǎn)品的交互式表示，以創(chuàng)建和測試設(shè)計概念。在此階段產(chǎn)生的一些常見文件有
網(wǎng)站/產(chǎn)品地圖是一種視覺方案，表示產(chǎn)品所有頁面之間的連接。它可以幫助團(tuán)隊可視化網(wǎng)站或應(yīng)用程序的結(jié)構(gòu)以及頁面/功能之間的連接。創(chuàng)建站點(diǎn)地圖是安排信息架構(gòu)的一部分。
站點(diǎn)地圖結(jié)構(gòu)示例。來源:uxforthemasses.com
用戶流程或用戶旅程地圖可視化了用戶在與產(chǎn)品的所有部分交互時應(yīng)該采取的步驟。通常，該方案包括所有的頁面、部分、按鈕和提供的功能，以顯示用戶移動的邏輯。
求職應(yīng)用用戶流程方案。來源:Michael Tsirakis在medium.com
線框圖是未來UI的藍(lán)圖?；旧希€框圖是一種方案，它顯示了如何安排頁面上的元素以及它們應(yīng)該如何表現(xiàn)，但沒有詳細(xì)說明這些元素應(yīng)該如何看起來。
躲貓貓手機(jī)應(yīng)用的線框圖示例
模型是設(shè)計創(chuàng)作的下一步，是代表最終產(chǎn)品實際外觀和感覺的靜態(tài)圖像。
原型是一個可以與之交互的模型:點(diǎn)擊一些按鈕，在不同的頁面之間導(dǎo)航，等等。原型可以在像Sketch或MockFlow這樣的原型工具中創(chuàng)建。使用模板，用戶體驗設(shè)計師可以在開發(fā)的早期階段創(chuàng)建用于可用性測試的交互式模型。
當(dāng)原型用于可用性測試時，從這些會話中收集的反饋和數(shù)據(jù)將被編譯成報告。
可用性測試報告有助于了解用戶對原型的反應(yīng)，確定痛點(diǎn)和需要改進(jìn)的地方。報告應(yīng)盡可能簡短，以視覺例子為主，而不是文字。
另一個經(jīng)常作為設(shè)計和開發(fā)團(tuán)隊之間的橋梁而創(chuàng)建的用戶體驗設(shè)計文檔是風(fēng)格指南。
UI風(fēng)格指南是用戶界面設(shè)計和實現(xiàn)的綜合手冊。它確保了整個產(chǎn)品的視覺表現(xiàn)和交互模式的一致性。樣式指南定義了應(yīng)該如何設(shè)計和安排UI元素和內(nèi)容類型。它包括以下指南:
軟件體系結(jié)構(gòu)文檔(SAD)包括解決方案架構(gòu)師做出的主要體系結(jié)構(gòu)決策。與上面提到的描述需要構(gòu)建什么的產(chǎn)品需求文檔不同，架構(gòu)文檔是關(guān)于如何構(gòu)建它——每個產(chǎn)品組件將以何種方式貢獻(xiàn)并滿足需求，包括實現(xiàn)需求的解決方案、策略和方法。
因此，軟件架構(gòu)文檔給出了產(chǎn)品結(jié)構(gòu)的概述，并確定了工作的全部范圍，將所有涉眾納入其中，并為開發(fā)團(tuán)隊提供了總體指導(dǎo)。
我們不建議太過詳細(xì)地列出所有需要完成的任務(wù)，而是把重點(diǎn)放在高層次的描述上。
通常，SAD包括以下部分。
概述和背景。簡要描述項目的主要目標(biāo)，你試圖解決的問題，以及你想要達(dá)到的結(jié)果。
產(chǎn)品描述。列出主要的功能性和非功能性需求，勾勒出項目范圍。
高級架構(gòu)描述。提供系統(tǒng)體系結(jié)構(gòu)的概述，并描述主要組件及其相互作用。簡要解釋架構(gòu)決策背后的原因以及影響您的方法的約束(例如，技術(shù)限制、遵從性需求等)也是值得的。
一個好的做法是用圖表和/或其他圖形材料來支持這一部分，以幫助理解和交流結(jié)構(gòu)和設(shè)計原則。
Azure web應(yīng)用程序架構(gòu)圖。來源:docs.microsoft.com
詳細(xì)的系統(tǒng)設(shè)計。提供關(guān)于關(guān)鍵系統(tǒng)組件及其交互方式的更詳細(xì)的描述。包括用于內(nèi)部和外部通信的API規(guī)范和協(xié)議。概述數(shù)據(jù)體系結(jié)構(gòu)、數(shù)據(jù)庫模式和數(shù)據(jù)完整性。
技術(shù)策略和解決方案。定義解決橫切關(guān)注點(diǎn)的策略，如可伸縮性、可靠性和安全性(例如，緩存、負(fù)載平衡、容錯等)。
基礎(chǔ)設(shè)施和部署。描述部署和運(yùn)行系統(tǒng)所需的硬件和基礎(chǔ)設(shè)施設(shè)置。包括網(wǎng)絡(luò)布局、服務(wù)器規(guī)范和部署圖。
技術(shù)設(shè)計文檔(TDD)，也經(jīng)常被稱為技術(shù)規(guī)范，提供了關(guān)于如何實現(xiàn)軟件系統(tǒng)需求的詳細(xì)的、低級的信息。它在系統(tǒng)架構(gòu)和實際代碼庫之間架起了橋梁，詳細(xì)說明了開發(fā)人員將遵循的特定配置、接口和編碼標(biāo)準(zhǔn)。
TDD包括組件設(shè)計、數(shù)據(jù)流程圖、算法、API端點(diǎn)和交互協(xié)議，確保開發(fā)人員擁有構(gòu)建軟件的清晰而精確的指南。
源代碼文檔是一種直接嵌入到解決方案源代碼中的技術(shù)文檔。它解釋了代碼是做什么的，它是如何工作的，以及為什么要做出某些決定。這可以包括對算法、配置和復(fù)雜邏輯的描述。
源代碼文檔以注釋的形式出現(xiàn)，可以是解釋特定操作的單行注釋，也可以是描述更復(fù)雜邏輯或數(shù)據(jù)結(jié)構(gòu)的更大的塊解釋。
文檔良好的代碼更容易維護(hù)和調(diào)試，因為開發(fā)人員可以理解代碼的意圖和功能，而無需破譯每一行。
QA活動是任何開發(fā)項目中不可缺少的一部分。與質(zhì)量保證相關(guān)的最常見的文件是
質(zhì)量管理計劃類似于專門用于測試的需求文檔。本文檔規(guī)定了產(chǎn)品質(zhì)量所需要的標(biāo)準(zhǔn)，并描述了實現(xiàn)標(biāo)準(zhǔn)的方法。該計劃有助于為產(chǎn)品經(jīng)理安排QA任務(wù)和管理測試活動，但它主要用于大型項目。
測試計劃是一個詳細(xì)的文檔，它概述了項目中預(yù)期測試活動的目標(biāo)、資源、范圍和時間表。它定義了QA團(tuán)隊的角色和職責(zé)，指定了要測試和不測試的內(nèi)容，描述了要執(zhí)行的測試類型(如單元測試、集成測試和系統(tǒng)測試)，以及要使用的方法和工具。
測試計劃還包括有關(guān)測試環(huán)境設(shè)置、風(fēng)險管理策略以及開始和完成測試的標(biāo)準(zhǔn)的信息。此外，它列出了預(yù)期的可交付成果，例如測試用例、報告和錯誤日志，并確定了負(fù)責(zé)批準(zhǔn)計劃及其結(jié)果的涉眾。
該文件作為一個藍(lán)圖，以確保測試是系統(tǒng)的、有效的，并與項目的質(zhì)量標(biāo)準(zhǔn)和目標(biāo)保持一致。
通常，測試計劃與測試策略會被混淆，但它們實際上是非常不同的。測試計劃是一個項目級別的文檔，關(guān)注于一個特定的軟件產(chǎn)品，而測試策略是一個過程文檔，它定義了整個公司采用的測試過程和標(biāo)準(zhǔn)(我們將在下面描述它)。
測試用例規(guī)范是一組詳細(xì)的操作，用于驗證產(chǎn)品的每個特性或功能。通常，QA團(tuán)隊會為每個產(chǎn)品單元編寫單獨(dú)的規(guī)范文檔。測試用例規(guī)范是基于測試計劃中概述的方法。一個好的實踐是簡化規(guī)范描述并避免重復(fù)測試用例。
測試檢查表是應(yīng)該在特定時間運(yùn)行的測試列表。它顯示完成了哪些測試以及失敗了多少測試。測試檢查表中的所有點(diǎn)都應(yīng)該正確定義。試著在檢查表中將測試點(diǎn)分組。這種方法將幫助你在工作中跟蹤它們，而不會丟失它們。如果這能夠幫助測試者正確地檢查應(yīng)用，你便可以在列表中添加評論。
大多數(shù)產(chǎn)品都包含API(應(yīng)用程序編程接口)，以支持與其他系統(tǒng)的數(shù)據(jù)交換。API文檔包含所有產(chǎn)品API及其規(guī)范的列表。它描述了請求、響應(yīng)、錯誤消息和其他基本細(xì)節(jié)，并告知開發(fā)人員如何有效地與系統(tǒng)API進(jìn)行交互。
顧名思義，用戶文檔是為產(chǎn)品用戶創(chuàng)建的。然而，他們有不同的類型，即終端用戶和系統(tǒng)管理員。因此，您應(yīng)該根據(jù)不同的用戶任務(wù)及其不同的經(jīng)驗水平來構(gòu)建用戶文檔。
為最終用戶創(chuàng)建的文檔應(yīng)該盡可能以最簡單的方式解釋軟件如何幫助解決他們的問題。這樣的用戶指令可以在設(shè)備上以打印形式、在線形式或離線形式提供。
以下是用戶文檔的主要類型。
快速入門指南提供了產(chǎn)品功能的概述，并給出了如何使用它的基本指南。
完整的手冊包括關(guān)于如何安裝和操作產(chǎn)品的詳細(xì)信息和說明。它列出了硬件和軟件需求，功能的詳細(xì)描述，關(guān)于如何充分利用它們的完整指南，示例輸入和輸出，以及可能的提示和技巧等。
故障排除指南向最終用戶提供有關(guān)如何查找和解決在使用本產(chǎn)品時可能出現(xiàn)的問題的信息。
在線最終用戶文檔可能以知識庫的形式出現(xiàn)，并包括以下部分:
由于用戶文檔是客戶體驗的一部分，因此使其易于理解并具有邏輯結(jié)構(gòu)非常重要。用戶指南用通俗易懂的語言編寫，包括視覺材料和一步一步的說明，可以成為強(qiáng)大的營銷工具，提高客戶滿意度和忠誠度。
此外，為了給最終用戶提供最好的服務(wù)，你應(yīng)該不斷收集客戶的反饋。wiki系統(tǒng)是維護(hù)現(xiàn)有文檔的更有用的實踐之一。如果您使用wiki系統(tǒng)，則不需要將文檔導(dǎo)出為可呈現(xiàn)的格式并將其上傳到服務(wù)器。您可以使用wiki標(biāo)記語言和HTML代碼創(chuàng)建wiki頁面。
系統(tǒng)管理員文檔是專門為負(fù)責(zé)計算機(jī)系統(tǒng)和網(wǎng)絡(luò)的安裝、配置、維護(hù)和故障排除的人員編寫的。它們提供了詳細(xì)的指導(dǎo)方針和說明，以確保IT基礎(chǔ)設(shè)施的正常運(yùn)行和安全性。
一些常見的系統(tǒng)管理員文檔包括
該文檔對于系統(tǒng)管理員有效地管理和保護(hù)組織的技術(shù)資源，確保IT操作的連續(xù)性和效率至關(guān)重要。
過程文檔涵蓋了圍繞產(chǎn)品開發(fā)的所有活動。保持過程文檔的價值在于使開發(fā)更有組織，更有計劃。
產(chǎn)品路線圖在敏捷軟件開發(fā)中用于記錄項目的遠(yuǎn)景、策略和總體目標(biāo)。它們有助于使開發(fā)過程與初始目標(biāo)保持同步。根據(jù)產(chǎn)品路線圖的類型，它可以表達(dá)高級目標(biāo)、任務(wù)優(yōu)先級、沖刺時間線或低級細(xì)節(jié)。
敏捷產(chǎn)品團(tuán)隊使用的產(chǎn)品路線圖有三種類型:
戰(zhàn)略路線圖是包含項目總體信息的高級戰(zhàn)略文件。戰(zhàn)略路線圖通常描述遠(yuǎn)景和長期目標(biāo)。在敏捷產(chǎn)品開發(fā)的情況下，路線圖可以按主題排列。主題是團(tuán)隊必須完成的多個任務(wù)，并且它們之間存在某種聯(lián)系。例如，一個主題可能聽起來像“提高頁面加載速度”，這需要許多操作。
將主題周圍的信息分組使路線圖具有高度的靈活性和可更新性，這非常適合基于sprint的開發(fā)。關(guān)于戰(zhàn)略路線圖，最好的建議是只包括重要的信息。否則，您可能會將您的路線圖變成一個笨拙的方案，難以理解和維護(hù)。
戰(zhàn)略軟件產(chǎn)品路線圖示例。來源:productplan.com
技術(shù)路線圖或IT路線圖是描述技術(shù)需求和技術(shù)實現(xiàn)手段的底層文檔。IT路線圖非常詳細(xì)。它們包含了每個可交付成果的信息，解釋了做出這樣一個決定的原因。
發(fā)布計劃為發(fā)布設(shè)定了嚴(yán)格的時間限制。發(fā)布計劃應(yīng)該關(guān)注實際的截止日期，而不是指定發(fā)布細(xì)節(jié)。
發(fā)布計劃示例。來源:productplan.com
強(qiáng)烈建議使用專用的路線圖工具來創(chuàng)建您自己的路線圖。一些在線工具如?：Strategic Roadmaps(以前的Roadmunk)、 ProductPlan,、Visor或Aha! 它們?yōu)閯?chuàng)建產(chǎn)品路線圖提供了各種模板，并且允許快速編輯和在所有團(tuán)隊成員之間輕松共享。
請記住，路線圖可以是陳述需求的產(chǎn)品文檔，這取決于它的類型。它還描述了開發(fā)過程并指導(dǎo)您的團(tuán)隊完成開發(fā)。
路線圖提供了一個高層次的概覽和戰(zhàn)略指導(dǎo)，而積壓的任務(wù)側(cè)重于實現(xiàn)這些更廣泛目標(biāo)所需的立即行動。
待辦事項是敏捷項目管理方法的基本組成部分，尤其是在Scrum這樣的框架中。它們?yōu)閳F(tuán)隊在開發(fā)產(chǎn)品時提供了一個清晰、可操作的計劃。
Scrum是如何工作的
產(chǎn)品待辦事項列表由需要解決的任務(wù)、特性、用戶描述和bug(如果有的話)的優(yōu)先級列表組成。當(dāng)計劃任何產(chǎn)品工作活動時，它作為需求的主要來源。隨著對產(chǎn)品及其用戶的了解以及市場條件的變化，它通常在項目的整個生命周期中不斷發(fā)展。
在類似scrum的方法中，沖刺待辦事項包含開發(fā)團(tuán)隊在沖刺期間承諾完成的所有特定任務(wù)。它是在sprint計劃會議期間創(chuàng)建的，因為團(tuán)隊根據(jù)優(yōu)先級和團(tuán)隊的能力從產(chǎn)品待辦事項列表中選擇項目。這個待辦事項列表對于每個sprint都是獨(dú)一無二的，并且是一個動態(tài)文檔，因為項目可以分解成更小的任務(wù)，在整個sprint中根據(jù)需要進(jìn)行調(diào)整以應(yīng)對挑戰(zhàn)和變化。
有兩種主要的方法來組織待辦事項。扁平待辦事項列表是一個簡單的待辦任務(wù)列表，一個功能接著一個功能。雖然它很容易創(chuàng)建，但它不能反映用戶的旅程，并且隨著它的增長而變得難以管理。
扁平的待辦事項列表vs用戶故事圖
相反，用戶故事地圖將用戶故事安排在二維布局中，幫助團(tuán)隊理解產(chǎn)品的功能，可視化用戶旅程，并對待辦事項進(jìn)行優(yōu)先排序。
一個將用戶故事映射分解為版本的示例。來源:Netcentric
還有許多其他類型的過程文檔值得創(chuàng)建，用于描述公司中的過程或反映特定項目中的特定過程。
標(biāo)準(zhǔn)包括團(tuán)隊在整個項目中遵循的所有編碼、測試和設(shè)計標(biāo)準(zhǔn)。
計劃、評估和進(jìn)度表通常是在項目開始之前創(chuàng)建的，并且可以隨著產(chǎn)品的發(fā)展而改變。
測試策略是描述組織整體軟件測試方法的高級文檔。它包括關(guān)于團(tuán)隊結(jié)構(gòu)和資源需求的信息，以及在測試期間應(yīng)該優(yōu)先考慮什么。測試策略通常是靜態(tài)的，因為它是為整個開發(fā)范圍定義的。
發(fā)布檢查表是在軟件發(fā)布之前要完成的任務(wù)和檢查的列表，確保沒有任何重要的事情被忽略。
工作底稿記錄了工程師在項目實施過程中的想法和想法。工作底稿通常包含一些關(guān)于工程師代碼、草圖和如何解決技術(shù)問題的想法的信息。雖然它們不應(yīng)該是信息的主要來源，但是跟蹤它們可以在需要時檢索高度具體的項目細(xì)節(jié)。
報告反映了開發(fā)過程中時間和人力資源的使用情況。它們可以按天、按周或按月生成。
一些過程文件是靜態(tài)的，描述了公司對特定過程的總體方法(例如，戰(zhàn)略、標(biāo)準(zhǔn)、檢查表等)，而另一些過程文件只涉及過程的特定時刻或階段(例如，中期報告)。結(jié)果，這些文檔很快就過時了。但是它們?nèi)匀粦?yīng)該作為開發(fā)的一部分，因為它們可能在將來實現(xiàn)類似的任務(wù)或維護(hù)時變得有用。
為項目創(chuàng)建技術(shù)文檔并不是一件容易的事。過程中涉及到許多不同的涉眾，每個涉眾都貢獻(xiàn)了特定的專業(yè)知識和觀點(diǎn)，以確保文檔準(zhǔn)確、全面和有用。
以下是所涉及的關(guān)鍵角色及其職責(zé)的列表。
業(yè)務(wù)分析師與客戶密切合作，收集并定義產(chǎn)品必須滿足的業(yè)務(wù)需求。他們還充當(dāng)非技術(shù)涉眾和技術(shù)團(tuán)隊之間的橋梁。它們確保技術(shù)文檔與業(yè)務(wù)目標(biāo)保持一致，并且非技術(shù)涉眾可以理解。此外，ba通常有助于創(chuàng)建用戶文檔。
市場分析師從最終用戶那里收集信息，以創(chuàng)建用戶角色和用戶場景。他們還研究市場，并通過驗證市場契合度和業(yè)務(wù)目標(biāo)為需求文檔做出貢獻(xiàn)。
項目經(jīng)理監(jiān)督文檔編制過程，確保其與項目時間表和目標(biāo)保持一致。他們負(fù)責(zé)與項目相關(guān)的大部分過程文件和計劃。
解決方案架構(gòu)師創(chuàng)建全面的架構(gòu)設(shè)計文檔。這些文檔概述了項目的擬議體系結(jié)構(gòu)，包括高層結(jié)構(gòu)、軟件設(shè)計以及各種組件和外部系統(tǒng)的集成。架構(gòu)師還有助于創(chuàng)建技術(shù)路線圖，并為項目設(shè)置技術(shù)標(biāo)準(zhǔn)和指導(dǎo)方針。
開發(fā)人員創(chuàng)建描述軟件元素的源代碼文檔。它們還解釋了特性是如何實現(xiàn)的，提供了代碼示例，并闡明了需要記錄的復(fù)雜技術(shù)過程。
UX設(shè)計師參與創(chuàng)建UX/UI設(shè)計文檔，包括界面描述、原型、站點(diǎn)地圖等。
QA工程師通過記錄測試協(xié)議、結(jié)果和配置來做出貢獻(xiàn)。他們確保文檔反映了有效測試軟件和報告錯誤的必要步驟。
技術(shù)作者主要負(fù)責(zé)起草和編輯文檔。他們與技術(shù)專家合作，收集準(zhǔn)確的細(xì)節(jié)，并以用戶友好的格式呈現(xiàn)。
這么長一長串的技術(shù)文檔看起來確實很嚇人，但你不必真的把它們寫在紙上——你也不必從頭開始創(chuàng)建它們。有很多專門的工具可以幫助你完成繁重的工作。
軟件開發(fā)團(tuán)隊有無數(shù)的協(xié)作工具。它們可以幫助說明需求、共享信息以及記錄特性和過程。
Atlassian Confluence是最流行的協(xié)作項目工具，它擁有管理產(chǎn)品需求和編寫文檔的完整生態(tài)系統(tǒng)。Confluence以穩(wěn)定的wiki系統(tǒng)和高效的用戶故事管理界面而聞名。
Document 360是一個為軟件即服務(wù)產(chǎn)品設(shè)計的自助知識庫/軟件文檔平臺。
一些。Ai是一個用于協(xié)作文檔創(chuàng)建、存儲、數(shù)據(jù)共享和使用wiki系統(tǒng)的工具。文檔是交互式的，這意味著開發(fā)人員可以將代碼塊或代碼片段直接嵌入到文檔中，并只需單擊一下即可共享。編輯完文檔后，您可以將其保存為PDF或markdown格式，并將其發(fā)布到任何其他平臺。
Github不需要介紹，除了那些想用它來編寫軟件文檔的人。它為您提供了自己的wiki系統(tǒng)，并允許將您的文檔轉(zhuǎn)換為引人注目的網(wǎng)站展示。
由于軟件文檔更容易在網(wǎng)絡(luò)上使用，因此必須以適當(dāng)?shù)母袷絼?chuàng)建。這就是使用基于文本的標(biāo)記語言的原因。最流行的一種是Markup，它可以很容易地轉(zhuǎn)換為HTML，并且不需要任何特殊知識。標(biāo)記在GitHub和Reddit上使用，基本上到處都是基于web的文檔。
因此，這里有一些Markdown編輯器可以幫助您為項目創(chuàng)建文檔。
Visual Studio Code是微軟為Windows、Linux和macOS開發(fā)的免費(fèi)開源代碼編輯器。它有許多特性和擴(kuò)展，包括用于項目管理和協(xié)作的特性和擴(kuò)展。
Typora是一個編輯器，它提供了一個無干擾的寫作環(huán)境和實時呈現(xiàn)markdown語法，以便于創(chuàng)建和編輯markdown文件。
iA Writer是一個極簡主義的文本編輯器，具有簡單，無干擾的界面和一系列有用的功能，包括語法高亮顯示，字?jǐn)?shù)統(tǒng)計和iCloud同步。
Quiver是一個用于Mac和iOS設(shè)備的筆記和代碼片段管理應(yīng)用程序。它允許用戶使用文本、代碼片段和標(biāo)記組合來創(chuàng)建和組織筆記。
使用特定于路線圖的工具是一個很好的做法，因為它們允許您快速共享信息，更新時間表或主題，添加新的點(diǎn)，并編輯整個結(jié)構(gòu)。大多數(shù)路線圖工具都提供了模板，因此您可以立即開始工作。
ProductPlan提供了路線圖、時間線創(chuàng)建、協(xié)作、優(yōu)先級和報告的特性，以幫助企業(yè)以更高效和有效的方式開發(fā)、共享和管理其產(chǎn)品路線圖。
啊哈!是一套適用于整個產(chǎn)品管理生命周期的工具，從創(chuàng)意到發(fā)布——包括路線圖。
Roadmunk提供自定義字段、拖放編輯、與其他工具的集成以及協(xié)作功能，使團(tuán)隊成員能夠?qū)崟r地協(xié)同工作。
KeepSolid的Roadmap Planner是另一個可視化的項目規(guī)劃和團(tuán)隊協(xié)作工具，用于創(chuàng)建項目路線圖，時間表和甘特圖。
所有的工具都提供免費(fèi)試用和付費(fèi)計劃，但在模板、路線圖數(shù)量和你可以與之分享的人方面有所不同。
最流行的用戶體驗設(shè)計工具是原型工具，它可以幫助創(chuàng)建草圖、模型、線框圖和交互式原型。
Sketch是一個簡單但功能強(qiáng)大的矢量設(shè)計工具，它有一個web應(yīng)用程序和一個Mac桌面客戶端。Sketch非常有名，而且非常簡單，為設(shè)計界面提供了足夠的功能。
草圖界面
InVision是最流行的原型工具之一。它以其協(xié)作特性和跨平臺功能而聞名，這使它成為設(shè)計界面的絕佳選擇。
UXPin是一個Mac和Windows設(shè)計工具，允許您構(gòu)建任何類型的藍(lán)圖。你也可以上傳其他產(chǎn)品的草圖或線框圖，并制作一個互動原型。
Adobe XD，其中XD代表體驗設(shè)計，是一款針對用戶體驗專家的產(chǎn)品。它允許設(shè)計師創(chuàng)建高保真的原型，并通過應(yīng)用程序分享。
創(chuàng)建API文檔的過程通常是自動化的。程序員或技術(shù)編寫者可以使用以下API文檔生成器。
Swagger是一套用于設(shè)計、構(gòu)建、記錄和使用RESTful web服務(wù)的工具。它為開發(fā)人員提供了一個直觀的界面，用于使用OpenAPI規(guī)范描述其api的結(jié)構(gòu)，包括端點(diǎn)、操作和模型。這允許自動生成可實時測試的交互式API文檔。Swagger的工具支持整個API生命周期，從設(shè)計和文檔到測試和部署。
Postman是另一個流行的API開發(fā)工具，用于構(gòu)建、測試和管理API。它還使團(tuán)隊能夠輕松地創(chuàng)建、共享和維護(hù)詳細(xì)的API文檔。該文檔是交互式的，允許用戶直接從文檔中執(zhí)行API請求，從而簡化了開發(fā)人員和涉眾的測試和集成。
RAML 2 HTML是一個將RAML (RESTful API建模語言)文件轉(zhuǎn)換為人類可讀的HTML頁面的工具。它使開發(fā)人員能夠直接從他們的RAML定義生成API文檔。
專業(yè)的技術(shù)作者經(jīng)常使用專門的軟件來創(chuàng)建高質(zhì)量的技術(shù)文檔。這樣的工具被稱為內(nèi)容管理系統(tǒng)(cms)，可以更容易地構(gòu)建、組織和管理各種文檔。CMS可以操作不同的文件格式，導(dǎo)入和存儲內(nèi)容，并允許多個用戶參與內(nèi)容開發(fā)。
MadCapFlare是一個強(qiáng)大的基于云的軟件，具有多渠道發(fā)布功能，多語言支持，廣泛的學(xué)習(xí)資源等。
Adobe RoboHelp是一個全功能的CMS，允許創(chuàng)建富媒體內(nèi)容，方便的微內(nèi)容管理，協(xié)作版本控制等。
ClickHelp是一個屢獲殊榮的平臺，提供從其他程序輕松遷移，靈活的權(quán)限選項和許多報告功能。
上一節(jié)中描述的許多工具都提供了用于創(chuàng)建技術(shù)文檔的各種模板。
下面的資源提供了與軟件開發(fā)和項目管理相關(guān)的各種模板。
Atlassian Confluence Templates在其產(chǎn)品中提供了通用的項目文檔模板。
ReadySET Pro是一個大型的HTML軟件文檔模板庫，包括規(guī)劃文檔、架構(gòu)、設(shè)計、需求、測試等等。
ReadTheDocs是一個使用ReadTheDocs平臺制作的一體化模板，提供了關(guān)于編寫您可能需要的每種文檔類型的說明，從架構(gòu)和UML圖到用戶手冊。
TemplateLab包含數(shù)千個用于各種目的的模板-包括項目管理。
可下載的模板可能更難管理和協(xié)作，但仍然可以讓您快速入門。這里有一些資源，你可以找到一些路線圖模板:
如果您正在尋找與qa（QA）相關(guān)的模板，您可能需要檢查這里:
軟件設(shè)計文檔有時也被稱為產(chǎn)品或技術(shù)規(guī)范。它是軟件文檔中最重要的部分之一。你可以調(diào)整其中一個模板來滿足你的需要:
如今，隨著越來越多的企業(yè)傾向于遷移到云，有一些知名的可信提供商提供培訓(xùn)和架構(gòu)示例，以促進(jìn)在其環(huán)境中的操作。
Amazon——AWS架構(gòu)中心為在云中運(yùn)行架構(gòu)工作負(fù)載提供AWS架構(gòu)指導(dǎo)、框架、工具和最佳實踐。
Microsoft -此資源提供了許多關(guān)于Azure架構(gòu)的有用資料，包括示例場景、架構(gòu)圖等。
Google -訪問Google云架構(gòu)圖示例的官方圖標(biāo)庫。
您應(yīng)該在沒有文檔和過多文檔之間找到平衡。糟糕的文檔會導(dǎo)致許多錯誤，并降低軟件產(chǎn)品開發(fā)的每個階段的效率。同時，沒有必要提供大量的文件和在幾份文件中重復(fù)信息。只應(yīng)記錄最必要和最相關(guān)的信息。找到適當(dāng)?shù)钠胶膺€需要在開發(fā)開始之前分析項目的復(fù)雜性。
盡量使您的文檔簡單且易于閱讀。它必須具有邏輯結(jié)構(gòu)并且易于搜索，因此要包含目錄。盡可能避免長文本塊，使用視覺內(nèi)容，因為這種方式對大多數(shù)人來說更容易吸收信息。
您還必須記住文檔是為誰寫的。如果它是面向終端用戶的，那么它肯定必須用簡單的語言編寫，這樣讀者就可以在不查閱技術(shù)詞典的情況下理解它。如果文檔是針對業(yè)務(wù)涉眾的，那么也應(yīng)該避免復(fù)雜的專業(yè)術(shù)語、技術(shù)術(shù)語或縮寫詞，因為您的客戶可能不熟悉它們。然而，如果是針對你的技術(shù)專家團(tuán)隊，確保你提供了他們堅持開發(fā)計劃并構(gòu)建所需設(shè)計和功能所需的所有準(zhǔn)確性和細(xì)節(jié)。
在相關(guān)文檔或文檔中的部分之間使用交叉鏈接。這對于相關(guān)信息分布在多個文件中的復(fù)雜文檔集尤其有用。
交叉鏈接不僅可以讓讀者快速跳轉(zhuǎn)到參考部分，而無需廣泛搜索，而且有助于避免冗余和方便更新。
文檔可以專門用于內(nèi)部或外部使用。在外部文件的情況下，最好對每個術(shù)語及其在項目中的具體含義提供清晰的解釋。文檔應(yīng)該用清晰的語言傳達(dá)想法，以便在涉眾、內(nèi)部成員和用戶之間建立通用語言。
適當(dāng)?shù)木S護(hù)非常重要，因為過時或不一致的文檔會自動失去其價值。如果需求在軟件開發(fā)期間發(fā)生變化，您需要確保有一個系統(tǒng)的文檔更新過程來包含變化。而且，如果在產(chǎn)品已經(jīng)上市時發(fā)生任何更新，通知客戶并刷新所有用戶文檔是至關(guān)重要的。
建立某種維護(hù)和更新計劃是一種很好的做法。你可以定期進(jìn)行更新，例如每周或每月，或者將其與你的開發(fā)計劃聯(lián)系起來，例如在每次發(fā)布后更新文檔。自動電子郵件或發(fā)布說明可以幫助您跟蹤開發(fā)團(tuán)隊所做的更改。
您還可以使用版本控制工具來更有效地管理此過程。它可以讓你跟蹤所做的更改，保留以前的版本和草稿，并使每個人保持一致。
敏捷方法基于協(xié)作方法來創(chuàng)建文檔。如果你想要提高效率，就應(yīng)該采訪程序員和測試人員，了解軟件的功能。然后，在你寫完一些文檔之后，與你的團(tuán)隊分享并獲得反饋。你也可以參加團(tuán)隊會議，定期查看看板。為了獲得更多的信息，試著發(fā)表評論，提出問題，并鼓勵他人分享他們的想法和想法。每個團(tuán)隊成員都可以為您生成的文檔做出有價值的貢獻(xiàn)。
如果可以的話，雇傭一個員工來處理你的文件是值得的。通常做這項工作的人被稱為技術(shù)作家。具有工程背景的技術(shù)作家可以從開發(fā)人員那里收集信息，而不需要別人詳細(xì)解釋發(fā)生了什么。在團(tuán)隊中嵌入一名技術(shù)作家也是值得的，把他安排在同一個辦公室以建立密切的合作關(guān)系。他或她將能夠參加定期會議和討論。
這里有一些建議，可以幫助你優(yōu)化和加快文件編寫和進(jìn)一步管理的過程。
想想最有效的傳遞信息的媒介。例如，制作音頻或視頻記錄對于需求捕獲、用戶指南等來說是一個很好的選擇。
鏈接到補(bǔ)充信息。插入到相關(guān)在線文章或信息頁面的鏈接，而不是在文檔中復(fù)制它們。
盡可能從代碼或數(shù)據(jù)庫生成圖。在為技術(shù)文檔創(chuàng)建圖表時，與其使用繪圖工具從頭開始構(gòu)建它們，不如在可能的情況下從代碼或數(shù)據(jù)庫生成它們，這樣會更有效。這可以使用各種流行編程語言和數(shù)據(jù)庫可用的工具和插件來完成，這些工具和插件可以根據(jù)代碼或數(shù)據(jù)庫模式自動創(chuàng)建圖。
利用截圖和視覺效果。使用截圖和其他圖片總是一個好主意，因為它們可以幫助你快速找到需要更新的內(nèi)容，這樣你就不必閱讀整個文本。
將文檔與源代碼一起保存。考慮將您的技術(shù)文檔與源代碼一起存儲，只是將它們分開。這有助于保持更新，并讓每個人都知道在哪里可以找到它。
自定義訪問以避免額外的更改。給潛在的作者編輯權(quán)限，而那些只有視圖訪問權(quán)限的人仍然可以看到信息，但不能修改它。
為作者提供方便的訪問。確保作者能夠快速方便地訪問文檔以進(jìn)行審查和更新。消除不必要的授權(quán)和/或批準(zhǔn)程序等障礙。
記得備份。養(yǎng)成定期備份的習(xí)慣，最好是在多個位置創(chuàng)建備份，比如云存儲或外部硬盤驅(qū)動器。此外，保留以前的版本并存檔項目中的電子郵件，因為將來可能需要用到它們。有一個備份計劃也是一個好主意，以確保您始終能夠訪問最新版本的文檔。請確保定期測試備份，以確保它們正常工作，并可在緊急情況下使用。
使用標(biāo)簽使搜索更容易。考慮使用標(biāo)記對文檔中的不同部分和主題進(jìn)行分類和標(biāo)記。在創(chuàng)建標(biāo)記時，考慮與每個部分最相關(guān)的關(guān)鍵字或主題，并確保它們在所有文檔中保持一致。此外，考慮使用層次標(biāo)記進(jìn)一步細(xì)化和組織內(nèi)容，使其更容易導(dǎo)航和搜索。
探索可能的溝通方式。如果文檔是共享知識的一種方式，那么想想其他的交流方式，或者找出為什么團(tuán)隊成員不只是談?wù)撍?。它有利于整體團(tuán)隊合作，并減少所需文檔的數(shù)量。
敏捷方法鼓勵工程團(tuán)隊始終專注于為客戶交付價值。在生成軟件文檔的過程中也必須考慮到這一關(guān)鍵原則。應(yīng)該提供好（全面）的軟件文檔，無論是針對程序員和測試人員的軟件規(guī)范文檔，還是針對最終用戶的軟件手冊。全面的軟件文檔是具體的、簡潔（簡明）的和相關(guān)的。
