編寫項目文檔時要問自己的 5 個問題

在開始實際撰寫又一個開源項目的文檔之前，甚至在採訪專家之前，最好回答一些有關新文檔的高級問題。

著名的傳播理論家 Harold Lasswell 在他 1948 年的文章《 社會中的傳播結構和功能 The Structure and Function of Communication in Society 》中寫道：

（一種）描述溝通行為的方便方法是回答以下問題：

• 誰
• 說什麼
• 在哪個渠道
• 對誰
• 有什麼效果？

作為一名技術交流者，你可以運用 Lasswell 的理論，回答關於你文檔的類似問題，以更好地傳達你的信息，達到預期的效果。

誰：誰是文檔的所有者？

或者說，文檔背後是什麼公司？它想向受眾傳達什麼品牌形象？這個問題的答案將極大地影響你的寫作風格。公司可能有自己的風格指南，或者至少有正式的使命聲明，在這種情況下，你應該從這開始。

如果公司剛剛起步，你可以向文件的主人提出上述問題。作為作者，將你為公司創造的聲音和角色與你自己的世界觀和信念結合起來是很重要的。這將使你的寫作看起來更自然，而不像公司的行話。

說什麼：文件類型是什麼？

你需要傳達什麼信息？它是什麼類型的文檔：用戶指南、API 參考、發布說明等？許多文檔類型有模板或普遍認可的結構，這些結構為你提供一個開始的地方，並幫助確保包括所有必要的信息。

在哪個渠道：文檔的格式是什麼？

對於技術文檔，溝通的渠道通常會告訴你文檔的最終格式，也就是 PDF、HTML、文本文件等。這很可能也決定了你應該使用什麼工具來編寫你的文檔。

對誰：目標受眾是誰？

誰會閱讀這份文檔？他們的知識水平如何？他們的工作職責和主要挑戰是什麼？這些問題將幫助你確定你應該覆蓋什麼內容，是否應該應該涉及細節，是否可以使用特定的術語，等等。在某些情況下，這些問題的答案甚至可以影響你使用的語法的複雜性。

有什麼效果：文檔的目的是什麼？

在這裡，你應該定義這個文檔要為它的潛在讀者解決什麼問題，或者它應該為他們回答什麼問題。例如，你的文檔的目的可以是教你的客戶如何使用你的產品。

這時，你可以參考 Divio 建議的方法。根據這種方法，你可以根據文檔的總體方向，將任何文檔分為四種類型之一：學習、解決問題、理解或獲取信息。

在這個階段，另一個很好的問題是，這個文檔要解決什麼業務問題（例如，如何削減支持成本）。帶著業務問題，你可能會看到你寫作的一個重要角度。

總結

上面的問題旨在幫助你形成有效溝通的基礎，並確保你的文件涵蓋了所有應該涵蓋的內容。你可以把它們分解成你自己的問題清單，並把它們放在身邊，以便在你有文件要創建的時候使用。當你面對空白頁無從著筆時，這份清單也可能會派上用場。希望它能激發你的靈感，幫助你產生想法。

via: https://opensource.com/article/20/9/project-documentation

作者：Alexei Leontief 選題：lujun9972 譯者：geekpi 校對：wxy

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive