国产xxxx99真实实拍_久久不雅视频_高清韩国a级特黄毛片_嗯老师别我我受不了了小说

資訊專(zhuān)欄INFORMATION COLUMN

【譯】如何寫(xiě)出一份優(yōu)秀的軟件設(shè)計(jì)文檔

Backache / 2153人閱讀

摘要:作為一名軟件工程師,我花了很多時(shí)間閱讀和編寫(xiě)設(shè)計(jì)文檔。在完成了數(shù)百篇這些文檔之后,我親眼目睹了優(yōu)秀設(shè)計(jì)文檔與項(xiàng)目最終成功之間的強(qiáng)烈關(guān)聯(lián)。讓我們來(lái)談?wù)剝?yōu)秀設(shè)計(jì)文檔的內(nèi)容,風(fēng)格和寫(xiě)作流程吧。現(xiàn)在,讓我們專(zhuān)門(mén)討論如何編寫(xiě)設(shè)計(jì)文檔并獲取反饋。

作為一名軟件工程師,我花了很多時(shí)間閱讀和編寫(xiě)設(shè)計(jì)文檔。在完成了數(shù)百篇這些文檔之后,我親眼目睹了優(yōu)秀設(shè)計(jì)文檔與項(xiàng)目最終成功之間的強(qiáng)烈關(guān)聯(lián)。

本文試圖描述什么使設(shè)計(jì)文檔變得更好。

本文分為4個(gè)部分:

為什么要寫(xiě)一份設(shè)計(jì)文檔

要包含在設(shè)計(jì)文檔中的內(nèi)容

怎么寫(xiě)

相關(guān)過(guò)程

為什么要寫(xiě)一個(gè)設(shè)計(jì)文檔?
設(shè)計(jì)文檔 - 也稱(chēng)為技術(shù)規(guī)范 - 描述了您計(jì)劃如何解決問(wèn)題。

已經(jīng)有很多文章闡述過(guò)為什么在開(kāi)工之前編寫(xiě)設(shè)計(jì)文檔很重要。所以我在這里要說(shuō)的是:

設(shè)計(jì)文檔是確保正確完成工作的最有用工具。

設(shè)計(jì)文檔的主要目標(biāo)是通過(guò)強(qiáng)迫您思考設(shè)計(jì)并收集其他人的反饋來(lái)提高您的效率。人們通常認(rèn)為設(shè)計(jì)文檔的目的是教會(huì)其他人關(guān)于某個(gè)系統(tǒng)或稍后作為文檔。雖然這些可能是一部分作用,但它們并不是最根本的目的。

作為一般經(jīng)驗(yàn)法則,如果您正在處理可能需要1個(gè)工程師月或更長(zhǎng)時(shí)間的項(xiàng)目,那么您應(yīng)該編寫(xiě)設(shè)計(jì)文檔。但不要止步于此 - 許多小型項(xiàng)目也可以從迷你設(shè)計(jì)文檔中受益。

如果您還在閱讀,您會(huì)相信設(shè)計(jì)文檔的重要性。但是,不同的研發(fā)團(tuán)隊(duì),甚至同一團(tuán)隊(duì)的工程師,經(jīng)常以非常不同的方式編寫(xiě)設(shè)計(jì)文檔。讓我們來(lái)談?wù)剝?yōu)秀設(shè)計(jì)文檔的內(nèi)容,風(fēng)格和寫(xiě)作流程吧。

設(shè)計(jì)文檔中應(yīng)該包含哪些內(nèi)容?
設(shè)計(jì)文檔描述了問(wèn)題的解決方案。由于每個(gè)問(wèn)題的性質(zhì)不同,您自然希望以不同的方式構(gòu)建您的設(shè)計(jì)文檔。

首先,以下是您應(yīng)該至少考慮在下一個(gè)設(shè)計(jì)文檔中包含的部分列表:

標(biāo)題和參與者
您的設(shè)計(jì)文檔的標(biāo)題,作者(應(yīng)該與計(jì)劃參與此項(xiàng)目的人員列表相同),檢查者(我們將在“處理”部分中詳細(xì)討論),以及最后更新日期。

概覽
高度概括的,公司的每位工程師都應(yīng)該理解并能夠通過(guò)閱讀概覽來(lái)決定是否有必要閱讀其余的文檔。最多3段。

背景
對(duì)手頭問(wèn)題的描述,為什么這個(gè)項(xiàng)目是必要的,人們需要知道什么來(lái)評(píng)估這個(gè)項(xiàng)目,以及它如何適應(yīng)技術(shù)戰(zhàn)略,產(chǎn)品戰(zhàn)略或團(tuán)隊(duì)的季度目標(biāo)。

目標(biāo)和非目標(biāo)
目標(biāo)部分應(yīng)包括:

描述項(xiàng)目的用戶(hù)驅(qū)動(dòng)影響 - 您的用戶(hù)可能是另一個(gè)工程團(tuán)隊(duì)甚至是另一個(gè)技術(shù)系統(tǒng)
指定如何使用指標(biāo)衡量成功 - 如果您可以鏈接到跟蹤這些指標(biāo)的儀表板,則可以獲得獎(jiǎng)勵(lì)
非目標(biāo)同樣重要,它描述了您不會(huì)修復(fù)哪些問(wèn)題,因此它也和目標(biāo)在同一頁(yè)面上。

里程碑
一個(gè)可衡量的檢查點(diǎn)列表,因此您的PM和您的經(jīng)理的經(jīng)理可以瀏覽它并大致了解項(xiàng)目的不同部分何時(shí)完成。如果項(xiàng)目超過(guò)1個(gè)月,我建議您將項(xiàng)目分解為面向用戶(hù)的主要里程碑。

使用日歷日期,以便考慮無(wú)關(guān)的延遲,假期,會(huì)議等。它應(yīng)該看起來(lái)像這樣:

開(kāi)始日期:2018年6月7日
里程碑1 - 以暗模式運(yùn)行的新系統(tǒng)MVP:2018年6月28日
里程碑2 - 下掉舊系統(tǒng):2018年7月4日
結(jié)束日期:將功能X,Y,Z添加到新系統(tǒng):2018年7月14日

如果其中一些里程碑的ETA發(fā)生變化,請(qǐng)?jiān)诖颂幪砑覽更新]子部分,以便相關(guān)方可以輕松查看最新的情況。

當(dāng)前解決方案
除了描述當(dāng)前的實(shí)現(xiàn)之外,您還應(yīng)該通過(guò)一個(gè)高級(jí)示例流來(lái)說(shuō)明用戶(hù)如何與此系統(tǒng)交互和/或數(shù)據(jù)如何通過(guò)它。

用戶(hù)故事是構(gòu)建此框架的絕佳方式。請(qǐng)記住,您的系統(tǒng)可能包含具有不同用例的不同類(lèi)型的用戶(hù)。

推薦解決方案
有人稱(chēng)之為技術(shù)架構(gòu)部分。再次,嘗試通過(guò)用戶(hù)故事來(lái)具體化這一點(diǎn)。可以包含許多子部分和圖表。

先提供一張大圖,然后填寫(xiě)大量細(xì)節(jié),確保即使你出去度假了,團(tuán)隊(duì)中的另一位工程師也可以閱讀它并按照你的描述實(shí)施解決方案。

替代方案
在提出上述解決方案時(shí),您還考慮了什么?替代品的優(yōu)點(diǎn)和缺點(diǎn)是什么?您是否考慮購(gòu)買(mǎi)第三方解決方案 - 或使用開(kāi)源解決方案 - 解決此問(wèn)題而不是構(gòu)建自己的問(wèn)題?

監(jiān)控和警報(bào)
我喜歡包括這一部分,因?yàn)槿藗兘?jīng)常事后才去考慮它們或者干脆忽略它們,當(dāng)事情出了岔子,他們一籌莫展。

跨團(tuán)隊(duì)配合方面
是否會(huì)增加外呼和開(kāi)發(fā)團(tuán)隊(duì)的負(fù)擔(dān)?
它會(huì)花多少錢(qián)?
它是否會(huì)導(dǎo)致系統(tǒng)延遲?
它是否暴露了安全漏洞?
有什么負(fù)面后果和副作用?
支持團(tuán)隊(duì)如何與客戶(hù)溝通?

討論
任何你不確定的公開(kāi)問(wèn)題,你想讓讀者權(quán)衡的有爭(zhēng)議的決定,建議未來(lái)的工作,等等。

詳細(xì)的范圍和時(shí)間表
本節(jié)主要是由參與該項(xiàng)目的工程師,他們的技術(shù)主管和他們的經(jīng)理閱讀。因此,本節(jié)在文檔的最后。

從本質(zhì)上講,這是您計(jì)劃執(zhí)行項(xiàng)目每個(gè)部分的方式和時(shí)間的細(xì)分。有很多內(nèi)容可以準(zhǔn)確地確定范圍,因此您可以閱讀這篇文章以了解有關(guān)范圍的更多信息。

我傾向于將設(shè)計(jì)文檔的這一部分視為正在進(jìn)行的項(xiàng)目任務(wù)跟蹤器,因此每當(dāng)我的范圍估計(jì)發(fā)生變化時(shí),我都會(huì)更新它。但這更多的是個(gè)人偏好。

怎么寫(xiě)
下面讓我們來(lái)談?wù)剬?xiě)作風(fēng)格。我保證這與你的高中英語(yǔ)課不同。

寫(xiě)得盡可能簡(jiǎn)單
不要試著寫(xiě)你讀過(guò)的學(xué)術(shù)論文。它們是為了給期刊評(píng)論家留下深刻印象。您的文檔是為了描述您的解決方案并從您的隊(duì)友那里獲得反饋而編寫(xiě)的。多運(yùn)用類(lèi)似這些:

簡(jiǎn)單的話

短句

項(xiàng)目符號(hào)列表和/或編號(hào)列表

具體的例子,如“用戶(hù)愛(ài)麗絲連接她的銀行賬戶(hù),然后…”

添加大量表格和圖示
表格通常可用于比較幾個(gè)可能的選項(xiàng),圖表通常比文本更容易解讀。我已經(jīng)用Google Drawing創(chuàng)建圖表了。

專(zhuān)業(yè)提示:請(qǐng)記住在屏幕截圖下添加指向圖表的可編輯版本的鏈接,以便以后在事情不可避免地發(fā)生變化時(shí)輕松更新。

包括數(shù)字
問(wèn)題嚴(yán)重程度通常決定了解決方案。為了幫助審閱者了解實(shí)際狀況,請(qǐng)包括實(shí)際數(shù)字,如數(shù)據(jù)庫(kù)行數(shù),用戶(hù)錯(cuò)誤數(shù),延遲 - 以及這些數(shù)據(jù)如何隨著使用情況而擴(kuò)展(請(qǐng)記住您的Big-O表示法?)。

試著變得有趣
規(guī)范不是學(xué)術(shù)論文。此外,人們喜歡閱讀有趣的東西,所以這是讓讀者保持參與的好方法。盡管如此,不要喧賓奪主。

進(jìn)行測(cè)試
在將設(shè)計(jì)文檔發(fā)送給其他人進(jìn)行審核之前,請(qǐng)自己作為審核人員過(guò)一遍。您對(duì)此設(shè)計(jì)有什么疑問(wèn)?然后先發(fā)制人地解決它們。

做假期測(cè)試
如果您現(xiàn)在無(wú)法訪問(wèn)互聯(lián)網(wǎng),那么您團(tuán)隊(duì)中的某個(gè)人是否可以閱讀該文檔并按照您的意圖實(shí)施該文檔?

設(shè)計(jì)文檔的主要目標(biāo)不是知識(shí)共享,但這是一種評(píng)估清晰度的好方法,以便其他人可以實(shí)際為您提供有用的反饋。

處理
設(shè)計(jì)文檔可幫助您在浪費(fèi)大量時(shí)間實(shí)施錯(cuò)誤解決方案或解決錯(cuò)誤問(wèn)題之前獲得反饋。獲得良好反饋有很多藝術(shù),但這是以后的事。現(xiàn)在,讓我們專(zhuān)門(mén)討論如何編寫(xiě)設(shè)計(jì)文檔并獲取反饋。

首先,參與項(xiàng)目的每個(gè)人都應(yīng)該參與設(shè)計(jì)過(guò)程。如果技術(shù)主管最終推動(dòng)了很多決定,那也沒(méi)關(guān)系,但是每個(gè)人都應(yīng)該參與討論并參與設(shè)計(jì)。因此,本文中的“你”是一個(gè)真正的復(fù)數(shù)“你”,包括項(xiàng)目中的所有人。

其次,設(shè)計(jì)過(guò)程并不意味著你盯著白板寫(xiě)些理論化的想法,隨意制作潛在的解決方案原型。這與在編寫(xiě)設(shè)計(jì)文檔之前開(kāi)始為項(xiàng)目編寫(xiě)生產(chǎn)代碼不同,不要那樣做。但你絕對(duì)應(yīng)該隨意寫(xiě)一些一次性代碼來(lái)驗(yàn)證想法。

之后,當(dāng)您開(kāi)始了解如何進(jìn)行項(xiàng)目時(shí),請(qǐng)執(zhí)行以下操作:

請(qǐng)您團(tuán)隊(duì)中經(jīng)驗(yàn)豐富的工程師或技術(shù)負(fù)責(zé)人成為您的評(píng)審員。理想情況下,這將是一個(gè)受到尊重和/或熟悉問(wèn)題細(xì)節(jié)的人。

進(jìn)入帶白板的會(huì)議室。

向這位工程師描述你正在解決的問(wèn)題(這是非常重要的一步,不要跳過(guò)它!)。

然后解釋你想到的實(shí)現(xiàn),并說(shuō)服他們這是正確的構(gòu)建。

在開(kāi)始編寫(xiě)設(shè)計(jì)文檔之前完成所有這些操作可以讓您在投入更多時(shí)間并接受任何特定解決方案之前盡快獲得反饋。通常情況下,即使實(shí)施保持不變,您的審核員也可以指出您需要覆蓋的極端案例,指出任何潛在的混淆區(qū)域,并預(yù)測(cè)您以后可能遇到的困難。

然后,在您撰寫(xiě)了設(shè)計(jì)文檔的粗略草稿之后,讓相同的審閱者再次閱讀它,并通過(guò)在設(shè)計(jì)文檔的“標(biāo)題和人物”部分中添加他們的名稱(chēng)作為審閱者來(lái)標(biāo)記它。這為審閱者創(chuàng)造了額外的激勵(lì)和責(zé)任。

在這方面,考慮為設(shè)計(jì)的特定方面添加專(zhuān)門(mén)的審閱者(例如SRE和安全工程師)。

一旦您和審核人員確定了,請(qǐng)隨時(shí)將設(shè)計(jì)文檔發(fā)送給您的團(tuán)隊(duì),以獲得額外的反饋和知識(shí)共享。我建議將反饋收集過(guò)程的時(shí)間限制在1周左右,以避免延誤。致力于解決人們?cè)谠撝軆?nèi)留下的所有問(wèn)題和評(píng)論。

最后,如果您,您的審閱者和其他閱讀該文檔的工程師之間存在很多爭(zhēng)議,我強(qiáng)烈建議您在文檔的“討論”部分中合并所有爭(zhēng)議點(diǎn)。然后,與各方召開(kāi)會(huì)議,當(dāng)面談?wù)撨@些分歧。

每當(dāng)討論主題長(zhǎng)度超過(guò)5條評(píng)論時(shí),轉(zhuǎn)向當(dāng)面討論往往效率更高。請(qǐng)記住,即使每個(gè)人都無(wú)法達(dá)成共識(shí),您仍然有責(zé)任進(jìn)行最后的溝通。

在最近與Shrey Banga談?wù)摯耸聲r(shí),我了解到Quip有一個(gè)類(lèi)似的過(guò)程,除了在您的團(tuán)隊(duì)中擁有經(jīng)驗(yàn)豐富的工程師或技術(shù)負(fù)責(zé)人作為審閱者之外,他們還建議讓不同團(tuán)隊(duì)的工程師審核該文檔。我沒(méi)有嘗試過(guò)這個(gè),但我當(dāng)然可以看到這有助于從不同角度的人那里獲得反饋,并提高文檔的一般可讀性。

完成上述所有操作后,即可開(kāi)始實(shí)施!對(duì)于額外的布朗尼點(diǎn),在實(shí)施設(shè)計(jì)時(shí)將此設(shè)計(jì)文檔視為活文檔。每次您更改原始解決方案或更新范圍的內(nèi)容時(shí),請(qǐng)更新文檔。這樣你就不必向所有利益相關(guān)者反復(fù)解釋事情,你會(huì)感謝我的。

最后,讓我們真正了解一下:我們?nèi)绾卧u(píng)估設(shè)計(jì)文檔的成功?

我的同事Kent Rakip對(duì)此有一個(gè)很好的答案:如果完成正確的投資回報(bào)率,設(shè)計(jì)文檔就會(huì)成功。這意味著成功的設(shè)計(jì)文檔實(shí)際上可能導(dǎo)致這樣的結(jié)果:

您花了5天時(shí)間編寫(xiě)設(shè)計(jì)文檔,這迫使您通過(guò)技術(shù)架構(gòu)的不同部分進(jìn)行思考

您可以從審閱者那里獲得反饋,即X是建議架構(gòu)中最具風(fēng)險(xiǎn)的部分

您決定首先實(shí)施X以降低項(xiàng)目風(fēng)險(xiǎn)

3天后,你發(fā)現(xiàn)X要么不可能,要么比你原先想要的要困難得多

您決定停止處理此項(xiàng)目并優(yōu)先處理其他工作

在本文開(kāi)頭,我們說(shuō)設(shè)計(jì)文檔的目標(biāo)是確保正確的工作完成。 在上面的示例中,由于這個(gè)設(shè)計(jì)文檔,您可能只花了8天時(shí)間而不是浪費(fèi)幾個(gè)月才能中止此項(xiàng)目。 對(duì)我來(lái)說(shuō)似乎是一個(gè)非常成功的結(jié)果。

如果您喜歡這篇文章,請(qǐng)?jiān)赥witter上關(guān)注我,了解有關(guān)工程,流程和后端系統(tǒng)的更多帖子。

原文地址

文章來(lái)源: 網(wǎng)易云社區(qū)

文章版權(quán)歸作者所有,未經(jīng)允許請(qǐng)勿轉(zhuǎn)載,若此文章存在違規(guī)行為,您可以聯(lián)系管理員刪除。

轉(zhuǎn)載請(qǐng)注明本文地址:http://specialneedsforspecialkids.com/yun/25383.html

相關(guān)文章

  • []每位開(kāi)發(fā)者都應(yīng)該知道SOLID原則

    摘要:開(kāi)閉原則軟件實(shí)體類(lèi),模塊,函數(shù)應(yīng)該是可以擴(kuò)展的,而不是修改。函數(shù)并不符合開(kāi)閉原則,因?yàn)橐坏┯行聞?dòng)物出現(xiàn),它需要修改代碼。 By Chidume Nnamdi | Oct 9, 2018 原文 面向?qū)ο蟮木幊填?lèi)型為軟件開(kāi)發(fā)帶來(lái)了新的設(shè)計(jì)。 這使開(kāi)發(fā)人員能夠在一個(gè)類(lèi)中組合具有相同目的/功能的數(shù)據(jù),來(lái)實(shí)現(xiàn)單獨(dú)的一個(gè)功能,不必關(guān)心整個(gè)應(yīng)用程序如何。 但是,這種面向?qū)ο蟮木幊踢€是會(huì)讓開(kāi)發(fā)者困惑或...

    go4it 評(píng)論0 收藏0
  • []148個(gè)資源讓你成為CSS專(zhuān)家

    摘要:層疊樣式表二修訂版這是對(duì)作出的官方說(shuō)明。速查表兩份表來(lái)自一份關(guān)于基礎(chǔ)特性,一份關(guān)于布局。核心第一篇一份來(lái)自的基礎(chǔ)參考指南簡(jiǎn)寫(xiě)速查表簡(jiǎn)寫(xiě)形式參考書(shū)使用層疊樣式表基礎(chǔ)指南,包含使用的好處介紹個(gè)方法快速寫(xiě)成高質(zhì)量的寫(xiě)出高效的一些提示。 迄今為止,我已經(jīng)收集了100多個(gè)精通CSS的資源,它們能讓你更好地掌握CSS技巧,使你的布局設(shè)計(jì)脫穎而出。 CSS3 資源 20個(gè)學(xué)習(xí)CSS3的有用資源 C...

    impig33 評(píng)論0 收藏0
  • 3月份前端資源分享

    摘要:面試如何防騙一份優(yōu)秀的前端開(kāi)發(fā)工程師簡(jiǎn)歷是怎么樣的作為,有哪些一般人我都告訴他,但是他都不聽(tīng)的忠告如何面試前端工程師 更多資源請(qǐng)Star:https://github.com/maidishike... 文章轉(zhuǎn)自:https://github.com/jsfront/mo... 3月份前端資源分享 1. Javascript 使用judge.js做信息判斷 javascript...

    nanchen2251 評(píng)論0 收藏0
  • 如何成為一名優(yōu)秀程序員

    摘要:前言羅子雄如何成為一名優(yōu)秀設(shè)計(jì)師董明偉工程師的入門(mén)和進(jìn)階董明偉基于自己實(shí)踐講的知乎為新人提供了很多實(shí)用建議,他推薦的羅子雄如何成為一名優(yōu)秀設(shè)計(jì)師的演講講的非常好,總結(jié)了設(shè)計(jì)師從入門(mén)到提高的優(yōu)秀實(shí)踐。 前言 羅子雄:如何成為一名優(yōu)秀設(shè)計(jì)師 董明偉:Python 工程師的入門(mén)和進(jìn)階 董明偉基于自己實(shí)踐講的知乎live為Python新人提供了很多實(shí)用建議,他推薦的羅子雄:如何成為一名優(yōu)秀...

    keelii 評(píng)論0 收藏0
  • 】 13簡(jiǎn)單優(yōu)秀編碼規(guī)則(從我15年經(jīng)驗(yàn))

    摘要:記住,帶有嚴(yán)格測(cè)試的代碼可能比沒(méi)有測(cè)試的代碼更有害。保持簡(jiǎn)單,極度簡(jiǎn)單不要編寫(xiě)復(fù)雜的代碼。并且它將是全球代碼文檔的良好開(kāi)端。使用這樣的迭代來(lái)部署質(zhì)量更新,而不是腰部時(shí)間和資源對(duì)不合理的愿望和犧牲與質(zhì)量。 原文地址:https://hackernoon.com/few-si... showImg(https://segmentfault.com/img/bVJdkG?w=1000&h=2...

    Eidesen 評(píng)論0 收藏0

發(fā)表評(píng)論

0條評(píng)論

最新活動(dòng)
閱讀需要支付1元查看
<