通向架構師的道路——漫談架構與設計文檔的寫作技巧

2020-09-05 瀟灑的程式設計師

前言：

這篇是一篇番外篇，沒有太多代碼與邏輯，完全是一種」軟「技巧，但是它對於你如何成為一名合格的架構設計人員很重要。

在此要澄清一點，架構師本身也是」程式設計師「，不是光動嘴皮子的傢伙們，如果你不是一名程式設計師出身那你根本談不上也不可能成為一名架構師。

那麼架構師還有哪些是作為一名程式設計師來說不具備的呢？

其中有一項能力就叫做」文檔寫作能力「。

一、Soft Skill與Hard Skill

作為一名架構師除得是一名資深的程式設計師外，它還必須具有相應的Soft Skill，其中有一名就叫做Documentation Skill。

1. 先來說一下Hard Skill

代碼與框架以及產品的靈活使用以及在相應的domain（如Insurance, Banking, CRM, DW。。。）上的經驗我們把它稱為Hard Skill，沒有這些技巧你就成不了一名合格的程式設計師。

程式設計師和IT是有區別的，程式設計師是IT業內的主力軍團，但是如果你是在一家網站或者是軟體司作需求分析的，哪怕是一個秘書，那你也是一個IT人員，對吧？所以這些東西是一個成為架構師的「硬」條件。

2. 什麼是Soft Skill

Soft Skill即指Documentation Skill, Presentation Skill，Communication Skill, 相應的Language Skill（不包括日本語，BS小日本）, Management Skill, Leader Ship, 這些.

當然，還有更多，更多。。。

2.1 Documentation Skill與Presentation Skill

今天主要講述的是Documentation Skill與Presentation Skill。

勿要小看這兩點，有人說他自己編程編得好，有人說自己的算法寫了如何如何精深，那麼。。。在現在這個團隊合作至上以及處於目前這樣的世界經濟大環境以客戶至上的背景下你所知道的的東西不能向其它人表達清楚，誰會理解你的想法，誰會接受你的理念，誰會選擇你公司的產品呢？

舉兩個例子：

蘇步青，他是大數學家，對吧，或許不少人不知道蘇步青在文學上的造詣也是很深的。

蘇步青曾說過：為什麼我喜歡語文，語言，因為我的論文，我的教材需要用語言去表達的，如果不把語言，語文學好我根本無法更精準更明白的去表達我的算法。

著名計算機學者C語言教程的作者譚好強曾經說過：能夠把複雜的問題用簡單直白的語言和框圖去表達出來，就是最好的論文。

再說個實際點的例子，你處於一個投標競賽中，你的設計或許是很好，可是如何讓客戶能夠理解和接受貴公司的設計方案呢？

那麼你需要在平時有意識的去提高或者我們說修練一下你的documentation skill，documentation skill與presentation skill是聯繫在一起的.

2.2 要善於懂得「包裝」

Presentation Skill即」宣傳、演示、演講、推銷&34;的促銷手法。

要學會「包裝」但不是扯蛋和吹牛，因為架構師拿出來的東西哪怕再漂亮，如果沒有內含那也是「濫竽充數」，被人識破後就一錢不值了。但是我們在有好的質量好的技術的基礎上善於去「包裝」它，相信你會離成功更近一步。

三、如何寫好一篇文檔和提高你的documentation skill

我在前公司有一陣沒空，一度讓其它幾個senior的Team Leader幫助我寫文檔，要求把設計按照需求能夠寫清即可。

送上來5篇文章，基本一篇都不能用.

第一次送上來，每篇都是講一個功能點，要不是冗長的一段沒意義的解釋，要不就是從官網直接COPY一段話下來，甚至連1,2,3,4都沒列出來，至少你要有個Advantage Points 或者說是Benefit和Disadvantage Points的對比吧.

第二次送上來，有了1，2，3，4，但是這下好了，全都標成1,2,3,4了。

要善於利用office編輯器中的「符號列表」，「4角星」代表亮點，「√&34;這個描述來說，你要畫的圖其實是建立在你的Hard Skill上的。

3.2.3 依照「八股文」來繪製設計圖

八股文就是有條理有章矩，不管什麼樣的文章你按照八股文去寫，寫出來都是一樣的層次，我們考四級英語的「寫作」這一本時其實也是有「章法」可循的對吧？

那麼這個設計圖的畫法也是有章可循的，也是有它的「八股文」樣板的。

前面說了，上手三套圖先聲奪人，搶人二目，那麼在架構設計文檔中還會充斥著種種模塊，子模塊，功能設計，功能點描述圖。。。如果你也來個一概而論，那就不是先聲奪人了，而是「喧賓奪主「了，呵呵呵。

這種子模塊、功能設計或者是功能點描述往往往以點、線為主，以點、線來連成一個面，而面中」鏤空「，如下面的樣例:

四、如何畫出準確且「漂亮」的設計圖呢

七叔：You are beautiful...啊...you are beautiful...You are so handsome...啊You are so handsome...

周星星：七叔，你不要這樣好吧。。。七叔。。。來人啊。。。

我在前一天即第二十五天中用來描述DbUnit的優點時用到了一套圖，它們是這樣的，大家還記得吧？

右邊的文字，沒什麼稀罕的，都是配色而己，關鍵在於左邊的這個圖。。。hoho，很多人問我用的是什麼工具畫的？

我告訴你們，我不是美工，我其實是在「拼圖」，如這幅圖的製作：

我是用了以下這5幅小圖標，拼制而成的：

不是這麼簡單的，隨便畫畫就成了，都要花功夫的、花心思去製作的。

  • 平時自己看到好的可以表達某個意義的圖片，存下來，分門別類
  • 看到人家寫的好的架構文檔，存下來，看看人家是怎麼去描述一個功能點的
  • 多搜集一些IT上專用的圖標，小圖片，logo

IBM的文檔是我看到過最恐怖的文檔，基本上這裡面的架構文檔出來都一個腔調，沒什麼文字，都是圖，連個「登錄過程」都用圖表達，連個「源碼check in check out」的管理流程都用圖表達。

保持你的圖系一致及風格的一致，你可以用卡通系、商務系任何一個系的圖來表達你的設計思想，但是當你的第一幅圖用的就是哪個系時，你的文檔中所有的圖都請用這個系列，而不建議你混雜使用你的圖系。

五、圖文混雜的技巧

什麼都不多說，上截圖，大家自己去感受一下吧

今天就說這麼多，希望對大家提高你的設計文檔寫作水平有所提高吧。

相關焦點

  • 20年美團架構師一份「架構寶典」竟涵蓋了架構設計和實踐技巧？
    本書從架構設計概念、方法、模式、實踐案例等4個方面進行闡述，內容豐富，凝聚了社區技術架構專家們的心血，涵蓋架構設計、技術選型、實際案例、技術原理等方方面面的知識，對於即將步入架構領域的技術專家和需要繼續提升專業素養的架構師而言都是不可或缺的案頭書。
  • 什麼樣的架構師修煉之道文檔,才能幫助大家修煉成為最出色的架構師?
    前言 卓越的軟體架構師從何而來? 所有程式設計師都有成為架構師的潛力，只要掌握了架構師的思維方式和工作方法，你也能成長為架構師。 本文教你如何像架構師那樣思考問題、理解需求、設計架構、評估結果、編寫文檔。
  • 架構師or普通的程式設計師，架構師優秀在哪幾方面？
    特定的技術架構師TSA主要從事特殊技術的規劃和設計，例如安全體系結構和存儲體系結構； 解決方案架構師SA的工作是專門從事解決方案的規劃和設計，「解決方案」一詞在中國已經達到了很高的水平，所謂的解決方案是不斷地將產品，技術或理論結合起來，以創建滿足用戶需求的選擇。大型公司將清楚的區分各種類型的架構師。小公司通常不是那麼注重區分了。
  • 阿里P8耗時一年最終總結出系統架構設計程式設計師向架構師轉型之路
    本書把「程式設計師向架構師轉型」作為切入點，提供架構師所需的各方面技能和相應的學習方法，包含針對轉型的一些思路、方法、工程實踐及可能會碰到的問題和解決方法。本書從架構師的定位及如何成為一名架構師的角度出發，除了技術和設計之外，還會介紹各項系統工程方法論和軟能力，旨在為廣大開發人員提供一套系統的、全面的轉型指南。
  • 架構老炮兒：談談 80% 的人關於架構師的誤解
    而做架構，需要全局思考各種技術、業務、資源要求，根據要求，尋找最合適的架構方案。事實上，如果你沒有從架構師的角度思考問題，帶領團隊，整體完成一個系統的架構設計與開發，那麼你永遠也不會了解如何做一個架構師。而你不去做一個架構師，又永遠沒有機會帶領一個團隊，完成一個系統的架構設計與開發。
  • 鋪平你的架構師之路！十年技術專家敬獻Java架構完美設計筆記
    （2）站在架構設計者的角度，思考一款優秀的系統架構應該具備哪些要素。（3）如何用「組合拳」來巧妙解決複雜問題。怎麼樣？你覺得你距離軟體架構師還有多少距離呢？在這裡，小編為大家帶來這篇致力於軟體架構師成長之路的Java架構完美設計，以實戰角度，為大家實現架構師之夢！！！
  • 太刺激了，這份阿里P8大牛出品的架構寶典，助你打開架構師大門
    軟體架構定義的多樣性和各個企業對架構師的定位不同，導致很多程式設計師在向架構師轉型的過程中有些茫然。小編在這裡分享一份由阿里P8大牛編寫的架構寶典，本書匯聚了國內一線網際網路公司的技術架構專家、架構領域布道者在架構方法論、微服務、業務架構、性能架構幾個方面的經驗，從系統架構設計和實踐方法與技巧兩個方面進行闡述，非常具有指導意義，希望讀者能在這裡找到解惑的鑰匙或突破瓶頸的方法。
  • 35 歲了，終於成為架構師了
    而做架構，需要全局思考各種技術、業務、資源要求，根據要求，尋找最合適的架構方案。事實上，如果你沒有從架構師的角度思考問題，帶領團隊，整體完成一個系統的架構設計與開發，那麼你永遠也不會了解如何做一個架構師。而你不去做一個架構師，又永遠沒有機會帶領一個團隊，完成一個系統的架構設計與開發。
  • 美團T9終於整理出Java架構之完美設計實戰開源文檔
    軟體架構師是每個程式設計師職業生涯中內功心法修煉的終極目標。要達到這個目標需要具備「十八般武藝，八十種技巧」，本書正是繼《Java代碼與架構之完美優化——實戰經典》《軟體品質之完美管理——實戰經典》之後，優秀軟體架構師又一本必讀書，也是「軟體架構師成長之路」系列教程的第三部作品，亦是本系列的收官之作。
  • 如何成為前端架構師?
    前端架構師，聽起來像是個很高大上的名詞，在大多數程式設計師眼中，架構師一般都來自於後端開發， Java或 C++，這些人往往有十八般武藝，能夠解決企業中出現的各種問題。前端架構師的概念已經漸漸進入了前端工程師的視野，無論何時，只要前端工程師還在工作，面試官就會問到，你的未來計劃是什麼？
  • 數位阿里P8架構師耗時半年,合力整理Java後端開發全棧技術文檔
    這讓我有很大的危機感，這個行業不進則退，新生代的碼農接收快，效率高，差的是老練的經驗，像我們這樣技術不夠精通，還有欠缺的，如果不努力完善自己的技術，隨時可能被淘汰，走上失業的道路。所以我也去問一些圈子裡的朋友，他們也是告訴我，就是平時多看看新出的書籍和和視頻，不能太安逸，自己要不斷擴充。
  • 架構師必備的十個重要技能
    架構師是程式設計師未來發展的重要方向，但是成為一個架構師並不容易，不僅需要豐富的開發經驗，還對各方面的能力都有著非常高的要求，這裡列舉了十個想要成為架構師必備的重要技能。讓我們從理論開始:了解基本的設計模式: 設計模式是架構師設計開發可維護、可擴展系統的一項最重要工具。通過設計模式你可以設計解決通用問題的可重用方案。由John Vlissides，Ralph Johnson，Richard Helm，Erich Gamma撰寫的《設計模式：可重用面向對象軟體的要素》一書每個從事軟體開發的人都有必要閱讀一番。
  • 阿里P8純手工打造架構師修煉手冊，讓你輕鬆駕馭分布式系統設計
    架構是一門藝術，也是一門技術，它不僅包含豐富的知識點，更考驗架構師的綜合能力。小編分享一份架構寶典架構設計是技術人員成長和晉升過程中必須掌握的技能，但目前業界缺乏架構師學習和培養方面體系化的知識和實踐的指導，這份寶典結合作者多年在架構設計方面的學習、思考、實踐，提出了完整的一套架構設計方法論，包括什麼是架構、架構設計的目的、架構設計原則、架構設計流程、架構設計模式和技巧、網際網路公司技術演進等內容
  • 如何從軟體開發人員成長為軟體架構師
    從開發人員到軟體架構師的旅程是一條充滿挑戰和懷疑的艱難道路。許多開發人員從初級開始就發展為高級和團隊領導角色。但是，作為一名軟體工程師，有多個發展方向。在本文中，為您提供一些有關成為軟體架構師的想法。軟體架構師是一位軟體專家，負責對給定的數字產品做出有關系統設計，基礎結構和技術標準（包括語言，工具和平臺）的行政決策。軟體架構師設定願景並監督系統的構建。 此外，軟體架構師應該能夠共享技術遠景和技術指導，並根據軟體項目的要求進行計劃。另一方面，軟體架構師應該知道他們將用來構建系統的學科，例如，開發環境，DevOps的設計，甚至方法論和最佳實踐。
  • 人人都是架構師：架構是一種能力，不是頭銜
    架構是一種能力，它不是頭銜。 換句話說，我們需要具備架構能力，但不一定要成為架構師。就像鄧公，他被稱為改革開放的總設計師，但他不是設計師。既然這樣，那我們還需要架構師嗎？還需要架構部門嗎？我給出的答案是：不需要，因為每個人都應該是架構師。
  • 阿里新產架構進階寶典限時開源,架構不止於思維
    為成為技術主管做準備從自我管理轉為管理團隊第二份文檔這份文檔不但通過真實案例講解架構設計流程和經驗，還總結了豐富的架構師工作原則和技巧同時也適合產品經理，測試人員、運維人員和其他行業從業者深入理解軟體架構設計工作。第一部分 軟體架構導論介紹軟體架構的基礎知識和架構師必備的設計思維。
  • 「企業架構」企業架構師vs解決方案架構師vs領域架構師
    它經常重用企業架構提供的其他元素(企業構建塊、企業功能、架構標準和指導方針)因此，企業架構師在企業架構團隊和組織的其他地方有許多不同的角色和職責。但是，人們可能會混淆這些角色和職責，例如，企業架構師有時會與解決方案架構師混淆，或者技術架構師與基礎設施架構師的角色混淆。這不僅是因為他們的職位聽起來相似，而且他們的職責也有部分重疊。
  • 微服務架構及設計模式還能這麼理解，不愧是阿里架構師
    以微服務架構為例，市面上關於微服務架構的資料有太多太多，但真正能系統的讓讀者對微服務架構腦子裡有一個很好的概念的資料並不多。而我今天要與大家介紹的文檔大家肯定可以從中獲益，了解微服務架構，掌握微服務架構，自己實踐微服務架構。
  • java架構師指南：成為java架構師之後該怎麼走
    作為一名java架構師，首先要將自己的主要職責概括為三個「負責」，即為新系統的架構設計、舊系統的架構演進負責;為業務的技術支撐負責;為團隊新人的成長負責;結合多年經驗，小編將java架構師之路分為三個階段：
  • 程式設計師如何向架構師發展？
    苦李，今天和我們公司前端大佬閒聊，說到從更高層次看待項目，例如，封裝前端組件庫，維護組件相關文檔等，他說到，重要的不是怎麼實現業務代碼，而是個人能為團隊帶來什麼。我想問下，後端代碼如果要優化，如何從更高的角度來進行，或是平時編寫代碼如何建立一種高層次架構思維，有哪些具體方面可以讓自己為團隊帶來價值。