跳至主要內容

寫作風格

目標讀者​

我們假設我們的目標讀者具備基本的軟體開發知識。我們的讀者知道如何使用他們的工具，例如他們的 IDE 和終端機視窗。我們的許多使用者都熟悉進階的軟體開發概念和技術，但我們無法在文件中假設這一點。我們不能假設我們的使用者有任何資料庫知識。

簡化​

盡可能簡單地寫作是技術溝通的一個良好原則。這比聽起來要困難，但額外的工作是值得的，以使文件更清晰、更易讀。當您為全球受眾寫作時，這一點尤其重要，他們並非所有人都精通英語。

  • 使用簡短的段落
  • 堅持使用簡短、簡單的句子。在可能的情況下，避免使用包含多個子句的句子。
  • 英文有很多同義詞 - 在可能的情況下，為工作選擇最簡單的可用詞。範例：「in」而不是「within」，「use」而不是「utilize」。
  • 使用項目符號列表將複雜的句子分解為組成點
  • 使用範例
  • 使用適當的文字強調，例如粗體和斜體，使您的寫作更清晰
  • 使用表格來列出複雜的資訊
  • 使用圖表使複雜的工作流程或概念更容易視覺化

語氣​

以冷靜、肯定的語氣寫作。我們的語氣是友善和直接的，但我們不使用俚語。

使用美式英語寫作​

美式英語是全球最廣泛認可的英語形式。使用美式英語的標點符號、語法和拼寫。例如

  • color 而不是 colour
  • behavior 而不是 behaviour
  • Prisma plans to 而不是 Prisma plan to

避免使用表情符號、俚語和隱喻​

避免使用表情符號、慣用語、俚語和隱喻。Prisma 有一個全球社群，這些項目的文化意義在世界各地可能有所不同，並且會隨著時間而變化。

避免使用不精確的代名詞，如「it」或「that」​

當您指稱特定的名詞時，請盡可能明確。除非您在先前的句子或子句中定義了專有名詞，否則請勿將該名詞稱為「it」。即使如此，如果您再次指定該名詞，您的寫作對於國際受眾來說可能會更清晰。特別是，避免以「It」開頭的句子。

以第二人稱寫作​

第二人稱（「您」）給人一種對話的語氣，並直接與讀者對話。避免使用第一人稱（「我」、「我們」、「讓我們」和「我們」）。範例

「您必須將整個 prisma/migrations 資料夾提交到原始碼控制。」

例外：當您指稱 Prisma 這個組織時，請使用「我們」。例如，這裡 Prisma（組織）建議一個行動方針

「我們建議您在您的應用程式中共享一個 PrismaClient 的單一執行個體」。

使用包容性語言​

當您以第三人稱指稱一個人或多個人時，請使用包容性、性別中立的語言。使用「他們/她們/他們的」而不是「他/他/他的」或「她/她/她的」。避免使用像「guys」這樣的特定性別的詞語。

術語​

術語：(n.) 特定行業或團體使用且其他人難以理解的特殊詞語或表達方式。

Prisma 文件包含許多技術細節，而術語是不可避免的。但是，我們力求盡可能少使用術語。

當您使用術語時，請遵循以下指南

  • 如果您可以用幾個詞來解釋該術語，那麼您可能會選擇在那裡立即解釋它。請自行判斷這是否最適合本文件。

  • 對於較長的解釋，請連結到其他地方的定義。

    • 如果該術語是 Prisma 特有的，則請連結到我們文件中的定義。

    • 如果該術語不是 Prisma 特有的，請檢查您是否可以透過網路搜尋快速找到定義。如果是這樣，則不要解釋該術語或連結到定義。我們可以合理地期望使用者知道該術語或自行找到解釋。

  • 僅在文件中邏輯部分的術語首次出現時進行連結。

    邏輯部分是我們可能會期望某人一次閱讀的文件部分。通常，它是一個頁面，或一個包含一個或多個標題部分的頁面中獨立的部分。

  • 當您連結到外部定義時，請選擇可信的來源。Wikipedia 是可以接受的，而官方第三方文件更好。

使用主動語態​

使用主動語態而不是被動語態。這是一種更簡潔、更直接的溝通方式。例如

  • （被動）JavaScript 中的 for 迴圈被程式設計人員用來...
  • （主動）程式設計人員使用 JavaScript 中的 for 迴圈來...

當我們的軟體或第三方軟體執行某項操作時，請說明哪個模組或元件執行該操作，如果這對使用者很重要。

  • 「Prisma Client 會將所有 DateTime 回傳為 ISO 8601 格式的字串。」

當模組或元件對使用者不重要時，請說 Prisma（或第三方軟體的名稱）執行該操作

  • 「Prisma 在尋找環境變數時會從系統的環境中讀取...」
  • 「這是因為 MongoDB 會回傳一個附加到您的 MongoDB 會話的游標...」

有時您可以完全省略作用元件或模組

  • 「請參閱 /directoryX 中產生的日誌檔案。」

要肯定​

使用肯定的語言。

好的

  • 使用 createMany 方法在單個交易中建立多個記錄
  • 您可以使用巢狀寫入同時建立使用者和該使用者的貼文

避免

  • 這個範例嘗試...
  • 您或許可以...
  • 您可以使用...

程序中肯定的語言

好的

  • 安裝 dotenv-cli

避免

  • 請安裝 dotenv-cli

使用「that」來釐清句子​

範例：「確保您重建您的綱要。」

請參閱：「That」作為名詞子句的連接詞。

使用現在簡單時態​

  • 使用現在簡單時態寫作。
  • 即使您想要寫關於使用者動作會導致發生的事情，也請使用現在簡單時態：說結果發生，而不是說它將會發生。
<!-- Good -->

When you run this command, Prisma writes the following log file.

<!-- Bad -->

When you run this command, Prisma will write the following log file.

指出何時為可選項目​

當段落或句子提供可選路徑時，第一句話的開頭應指出它是可選的。例如，「如果您想了解更多關於 xyz 的資訊，請參閱我們的參考指南」比「如果您想了解更多關於 xyz 的資訊，請前往參考指南」更清晰。

這個方法讓不想深入了解 xyz 的人能盡早停止閱讀句子。同時，它也讓想深入了解 xyz 的人能更快地意識到學習的機會，而不是意外跳過這段文字。

對於程序中的可選步驟，一個簡潔的表達方式是在步驟前加上「可選：」。例如：

  1. 可選：在標籤欄位中，為您的檔案指定一個或多個標籤。多個標籤之間用逗號分隔。

程式碼範例​

所有查詢範例都以常數開始。這會給你一個名詞，以便在文件中稍後引用，並且在大多數情況下，這會使範例更清晰。

範例

const aggregations = await prisma.user.aggregate({
  ...
})