我將如何爲我的公司創建技術標準文檔？

Question

我是我公司的產品工程總監。我的首席執行官要求我創建一個技術標準文檔，解釋諸如我們使用的技術，適應新技術的政策以及像單元測試覆蓋的代碼百分比這樣的設計標準。我從來沒有這樣做過，我花了大量的時間搜索網絡的例子，但我一直沒有找到。我發現的最接近的是描述單個產品技術規格的文檔。不過，我試圖爲整個公司定義這一點。有人可以提供如何格式化/組織這個文件的例子，以及典型的內容是什麼？謝謝！

Answer 1

你應該考慮一下爲什麼你被要求寫文檔。它是否旨在幫助您的工程和產品開發過程？潛在投資者將收到的盡職調查包含在內嗎？您是否想要實現某種類似ISO9000等流程認證？這是否簡單的使命陳述行話充滿絨毛，將沒有真正的目的？

關你可能想談談我的頭頂：

• 採用適當的技術
• 如何選擇和購買決定會進行：在防禦工程基礎？
• 跟上了技術接受社會的最佳實踐，我們部署
• 識別和使用最好的工具來做，以提高開發人員的生產力
• 你的態度，開源解決方案（也許OK，只要解決問題和合法簽出;您可能希望在更常見的開源許可中包含策略）
• 您的開發過程。你使用正式的方法（瀑布/敏捷/混亂/極端/ TDD/...）或更特別的東西？那麼開發工作流程呢？ （我的意思是錯誤跟蹤，源代碼提交的控制，發佈程序等等。）
• 你允許工程師有時間進行專業開發嗎？ （會議，課程，副項目）？ Google和其他地方的「20％時間」有什麼關係？

Answer 2

你應該繼續。這通常是您在網上找不到的內部文檔。

你寫的最好的文檔將來自你自己，通過寫下大圖片的東西。這樣一份文件的組織內容對你公司的業務和文化來說太具體了。

Answer 3

有很多方法來處理這樣的文件。確切的內容取決於你想完成什麼。

下面是一個示例（link to page/direct link to PDF）。它似乎專注於列出組織中現有的，逐步淘汰的和即將推出的技術，以便供應商知道他們將與之合作。這是一種方法的例子。

顯然，這個特定的文檔不包括像單元測試這樣的設計標準。再次，內容取決於你的特定目標......

Answer 4

首席執行官們只問他們是否有嚴重的問題。你的第一步是和他談談他正試圖解決的問題。這可能是誤解，成本問題，上市時間的挑戰，供應商鎖定戰略要素的問題，人力資源部門找不到合適的資源等等。你的首席執行官將非常感謝你提出的問題，以弄清楚他正試圖解決什麼問題。它還會讓您瞭解所需的時間線和詳細程度。

我已經創建了兩個。一個用於半導體生產，一個用於數據中心整合。這是我使用的工作流程。

讓你的建築師打造高水平的視覺 請通過技術拆分，以確保升級更容易，並且分佈 指定一個文件所有者每種技術/團隊 指定一個技術領導自己的連貫性維基結構並審查依存關係 委派每個團隊通過SWOT和決策記錄每項技術 指定一名優秀的項目經理，建立穩固的治理並在各個級別進行大量溝通 三週後，回去制定一項重點策略在標準化和消除威脅SWOT 如果需要，你可以把一些流程傢伙（ITIL，ISO等適合你的公司）放在它上面點。之前這樣做是浪費資源。

這項工作的關鍵成功因素是專家分配的所有權，自下而上的參與和買入，強有力的治理和（一如既往）的溝通。

這不是一件容易的事情，它具有深遠的戰略影響。根據您的公司的規模以及員工的經驗，您可能需要獲得一些諮詢服務。如果你這樣做，看看你的供應商，並從一個快速發展的行業（IT /半導體/汽車等）挑選人

如果您需要更多幫助，請隨時與我聯繫。我沒有找工作，也沒有試圖向你推銷諮詢服務，承諾。

Answer 5

對於大公司來說，有一個「最佳實踐」方法。治理「工件」或文檔有層次結構。最高級別是業務戰略和IT戰略。這似乎超出了你的範圍。應該有一套IT原則（見開放小組），描述您想要的品質，這些原則可以具有頂層的「指導原則」，然後是具體的主題領域原則，如數據管理，應用程序設計，基礎架構和甚至是IT管理。但這不是你要求的。當涉及到政策和標準時，理解差異是很好的。政策是一般性的，關於控制和管理，標準是具體的，關於做什麼和不做什麼。還有關於如何做事情的指南，或者你不想過於迫切的領域，但提供最好的方式去做事情。這些通常都在非常具體的領域......例如：測試自動化文檔;代碼質量分析;元數據收集;批量工作自動化....在這個級別。但是如果你想制定嚴格而快速的規則，而不是有用的指導，這些可能就是標準。

所以，回到標準和政策......你們都需要。該政策應界定主題領域，界定權力 - 行政職位/頭銜自己的責任。定義。這個非常重要。即使您的定義不包含一般行業慣例中所有可能的含義，您也必須說明XYZ公司和本政策背景下的含義，以減少對政策解釋的爭論。

這裏有例子。通常州政府有很好的例子，因爲他們傾向於喜歡並需要IT的「治理」，他們的文件通常是「公共信息」。即使是外國政府（我發現了澳大利亞的一些很好的例子）。

標準遵循政策並列出具體規則，而不僅僅是管理框架。

所以，不，你不應該只是從心寫信，或寫任何你想要的。有一種方法可以做到這一點。你可以開始編寫標準，這不是一個不錯的開始。你不只是開始爲陽光下的一切寫下標準文件。您可以確定需要的區域。設計質量或可管理性出現動盪或任何原因導致疼痛的地方。但是，您需要高於標準的政策文件層來說明誰負責執行他們，誰擁有他們，誰負責審查和改變。是否有執行指導委員會？是否有技術所有權委員會會引入正確的中小企業來編寫和審查標準，以確保其技術上合理並解決實際問題....不會造成更多的傷害而不是更好的損害？

因此，也許可以嘗試寫一個標準或兩個標準（在互聯網上找到一個好的模板或示例），然後想象一下爲提供新標準骨幹和活力所需的策略 - 即強大的贊助商，合規過程和審查過程。每項政策都可以並且應該有一系列標準。因此，請列出候選人名單 - 可能有一些優先事項並向老闆顯示。與他談談政策和標準的共生。你會成爲英雄。