為您的開源專案提供良好的文檔是一項重要（且經常被忽視）的功能，可以促進採用並展示您的軟體的全部潛力。

不幸的是，文檔的增長速度通常比程式碼慢得多，主要是因為一些看起來相當簡單的實現，會產生大量可能的用例和變化。不可能涵蓋所有可能的場景，這就是為什麼技術作家的首要工作是確定範圍和確定優先級。關注基本知識非常重要，必須首先記錄以支持最常見的用例。

在這篇文章，我將分享一些技巧，為您的專案打造一個好的 README 文件。

原文出處：https://dev.to/erikaheidi/documentation-101-creating-a-good-readme-for-your-software-project-cf8

README 檔案

專案的 README 文件通常是用戶與您的專案的第一次接觸，因為這是他們在訪問您的專案時首先看到的內容。這就是為什麼優先考慮將好的 README 作為專案文檔的起點很重要。

自然地，不同的專案在 README 中有不同的東西要展示，但這些技巧應該作為大多數軟體專案的良好起點。

1. 少即是多

你可能想把所有東西都放在你的 README 中，比如如何安裝和使用項目，如何部署，如何調試......更詳細地涵蓋這些主題的更完整文檔的鏈接。

當您開始時，只有一個 README 就可以了。很長的 README 沒有吸引力，因為沒有目錄或菜單可供導航，因此更難找到訊息，這最終不利於良好的用戶體驗。鏈接到相關資源的較短的自述文件使專案看起來更有條理且不那麼複雜。

如果我不想為這個專案創建一個專門的文檔網站怎麼辦？那麼，在這種情況下，您可以考慮在根目錄中創建一個 docs 文件夾，您可以在其中保存額外的 markdown 文檔，這些文檔可以直接從您的代碼託管平台（假設是 GitHub）瀏覽。

2. 將 README 拆分為其他文檔

對於存儲庫中的文檔，您可以在應用程式的根目錄中創建一個“/docs”目錄，並使用“/docs/README.md”文件作為文檔的入口點或索引。

此文件夾的內容大概就像：

• installation.md - 詳細顯示如何安裝項目的文檔。
• usage.md - 項目使用情況和主要命令的更詳細視圖。
• advanced.md - 包含一些進階使用選項和用例的文檔。

這些只是一些可以作為起點的想法。如果您覺得需要創建一個包含子文件夾的更複雜的結構，您應該認真考慮為您的項目創建一個專門的文檔網站（我們將在本系列的後續文章中介紹）。

3. README 文件要點

以下是您的 README 文件中絕對應該包含的一些內容：

• 項目的大致概述，包括編寫它的語言、它的作用、它為什麼有用；
• 安裝要求；
• 安裝文檔的鏈接；
• 使用概述，讓用戶簡要了解如何執行它；
• 故障排除或測試提示（可以是指向單獨文檔的鏈接）；
• 連接到其他資源以了解更多訊息。

理想情況下，這些應該是簡短的說明，可在必要時鏈接到更全面的文檔。

根據項目的規模和目標，您應該考慮將其他內容放在那裡：

• 指向 CONTRIBUTING.md 文檔的鏈接，其中包含有關用戶如何為您的專案做出貢獻的詳細訊息
• 指向包含項目行為準則的 CODE_OF_CONDUCT.md 文檔的鏈接。

如果您的項目託管在 GitHub 上，這些將顯著顯示在右側欄的項目頁面中，就在“關於”部分的正下方。

示例結構

以下是 markdown 的一般結構，您可以將其用作構建專案自述文件的基礎：

# Project Name

A paragraph containing a high-level description of the project, main features and remarks.

## Requirements

Here you should give a general idea of what a user will need in order to use your library or application. List requirements and then link to another resource with detailed installation or setup instructions.

- Requirement one
- Another requirement

Check the [installation notes]() for more details on how to install the project.

## Usage

Include here a few examples of commands you can run and what they do. Finally link out to a resource to learn more (next paragraph).

For more details, check the [getting started guide]().

## Useful Resources

Include here any other links that are relevant for the project, such as more docs, tutorials, and demos.

4. 使用徽章

您可以使用徽章通過自動從專案中提取的快速訊息來豐富您的 README，例如最新構建的狀態、最新的穩定版本、專案許可證等。

有不同的服務可以為開源專案提供徽章。正如@mohsin 在這篇文章的評論部分所指出的，您可以直接從 GitHub Actions 中提取徽章，方法是轉到您的工作流程頁面，單擊右上角顯示的三個點，然後從中選擇“創建狀態徽章”菜單：

這將向您顯示一個帶有降價代碼的對話框，您可以將其複製並貼上到您的 README 文件中。

另一個不錯的選擇是使用網站 Shields.io，它提供了幾種不同的徽章，您可以在您的開源項目中免費使用。

例如，這是顯示最新版本 yamldocs 的圖像 URL：

https://img.shields.io/github/v/release/erikaheidi/yamldocs?sort=semver&style=for-the-badge

這會生成以下徽章，顯示最新版本：

這是帶有多個徽章的 README 示例：

結論

文檔是任何軟體專案的重要組成部分，應該從一開始就認真對待。最好的開始方式是創建一個好的自述文件，向用戶顯示基本信息，而不是用他們可能不需要的內容來淹沒他們，以便開始使用您的專案。