操作指南

本指南改編自 Good Docs 計畫的操作指南。請使用本指南完成 how-to template.

介紹

操作指南會引導使用者完成解決特定問題所需的一系列步驟。它會向使用者展示如何使用 Koha 解決實際問題或完成任務，例如如何關閉圖書館。

Note

任務是指使用者使用 Koha 完成特定目標的操作。完成一個目標可能需要多個任務。

操作指南清楚地描述了完成某項任務的一系列步驟。操作指南假設使用者已具備 Koha 的基本知識。

How-tos are often confused with tutorials. How-tos are task-oriented, while tutorials are learning-oriented. The differences between the two:

自學課程

操作方法

學習導向: 幫助初學者或專家使用者透過實作學習新功能。

任務導向型: 幫助專業使用者完成任務或解決問題。

從頭到尾都遵循精心策劃的路徑。

致力於取得成功，並引導使用者以最安全、最可靠的方式達成目標。

消除任何意外情況，確保使用者順利完成任務。

提醒使用者可能出現意外情況，並指導使用者如何應對。

假設使用者沒有任何實務知識，必須明確說明任何工具、檔案組態、概念細節等。

假設使用者具備實務知識。

我為什麼需要操作指南？

操作指南通常用於幫助進階使用者正確完成任務。它可以:

  • 展示 Koha 的功能。

  • 引導使用者透過一系列有序的步驟，使用Koha解決現實世界中的問題。

  • 幫助解答使用者可能提出的具體問題。

  • 讓使用者在使用Koha 時感到舒適。

  • 改善使用者體驗，並透過減少支援請求數量來幫助降低成本。

如果操作指南編寫得當，並說明了完成任務所需的任何先決知識，那麼新使用者也可以從操作指南中受益。

在編寫操作指南之前

在開始編寫操作指南之前，先識別:

  • 操作指南的主要受眾或使用場景。

  • 使用者在現實世界中完成任務時可能遇到的不同場景。如果發生這種情況，就會發生那種情況。例如，在…的情況下，另一種方法是…

  • 完成任務最可靠、最安全的方法。提供多種完成任務的方法，實際上是在引導使用者思考不同的方案並做出選擇。透過簡化選項，可以節省使用者的時間和精力。

  • 使用者在完成任務時可能遇到的潛在場景及其相應的解決方案。

編寫操作指南的最佳實踐

  • 每篇操作指南都應針對一個邏輯目標（任務）。盡量避免只有指南中的一小部分內容與使用者相關的情況。

  • 讓使用者做好應對意外情況的準備，提醒使用者可能出現的情況，並提供應對指南。例如，在使用者完成任務時，會新增警告、提示或備註等標註，以傳達重要訊息。

  • 使用條件命令。如果你想要 x，就做 y。要實現 w，就做 z。

  • 不要解釋概念。

  • 有時提供一些指向輔助文件的連結會很有幫助，以便使用者獲得更多資訊。尤其是在使用者可能需要背景知識或`概念 <https://gitlab.com/tgdp/templates/-/tree/main/concept>`_資訊和`參考<https://gitlab.com/tgdp/templates/-/tree/main/reference>`_資料時。但是，請避免在操作指南中提供過多連結。盡量讓使用者在一個頁面上完成所有操作，並將其他資源的連結放在頁面底部。

  • 避免重複記錄完成相同任務的多種方法。如果完成一項任務有多種方法，請選擇並記錄最常用或建議的方法。其他方法應省略，或透過提供連結或參考文件的方式提及。

  • 務必確保操作指南中的步驟在技術上準確無誤。從頭到尾測試您的操作指南，以便發現遺漏的步驟、錯誤的細節、順序錯誤以及可能阻礙使用者操作的資訊缺失。如果無法自行測試，請開發人員、圖書館員或相關領域專家向您示範這些步驟，並盡可能錄製簡報流程。

  • 每次重要產品發佈後都要重新測試說明書，以確保說明書仍然準確無誤。

  • 冗長的操作指南會讓使用者感到不知所措。操作指南每次只專注於一項任務，每個任務的步驟最多控制在 8-10 個。如果任務過於龐大複雜，請將其分解為多個邏輯清晰的子任務，每個子任務都包含各自的步驟。

關於 "概述" 部分

請使用此部分提供以下資訊:

  • 對使用者可以解決或完成的問題或任務進行清晰的描述。

  • 使用者何時以及為何可能想要執行此任務。例如，在建立拉取請求的指南中，您可以告訴使用者，拉取請求用於讓其他人知道您已將變更推送到典藏庫分館。

本操作指南假設使用者對 Koha 有基本的了解，並且知道自己想要達成什麼目標。

例如:

  • 本指南解釋如何在 Bugzilla 中建立問題。您可以建立問題來追蹤 Koha 模組和工具的錯誤、改進建議和新功能。

  • 本指南說明如何暫時關閉圖書館。暫時關閉圖書館可能需要在Koha 系統中進行多項更改，例如通知館員和讀者、更新通知以及延長借閱期限。

關於 "開始之前" 部分

{此部分為可選部分}

本節介紹使用者在嘗試操作指南之前需要了解或具備哪些知識。透過提前說明這些要求，您可以避免使用者操作到一半才發現需要閱讀其他文件才能繼續。

請使用本節說明本操作指南的任何先決條件，例如:

  • 熟悉 Koha 模組或功能

  • 所需的任何資訊，軟體或工具

  • 要設定和配置的環境

  • 身份驗證和授權訊息

  • 其他指南或資訊可供閱讀

  • 提供相關流程或資訊的連結，或提供任何關於如何獲取所需資訊的有用提示。

為了便於理解，先決條件可以分為背景知識和軟體先決條件等類別。

可選地，您也可以提供提示，讓使用者知道他們可能來錯地方了，並提供更合適的選項。例如，如果您是 Linux 使用者，請參閱 {相關 Linux 操作指南的連結}。

例如:

Before you begin, ensure you have:

* A conceptual understanding of RESTful APIs.

Before you begin, ensure you have:

* API credentials for the v3.5 API.
* Access to the Postman application.
* (Optional) A development environment (IDE) that displays API responses formatted for readability.

關於 "步驟" 部分

步驟部分用於描述使用者需要執行的操作。請使用有序列表來記錄操作步驟。範本中的步驟組織方式如下:

{Task name}

{Optional: Provide a concise description of the purpose of this task. Only
include this if the purpose is not clear from the task title.}

1. {Write the action to take here. Start with a verb.}

   {Optional: Explanatory text}

   {Optional: Code sample or screenshot that helps your users complete this
   step}

   {Optional: Result}

   {Optional: If needed, you can add substeps below a primary step.}

步驟範例:

Create a pull request

Pull requests are used to inform others of changes you have pushed to a
branch in a repository. Once a pull request is opened, you can collaborate
with reviewers and make changes before merging into the base branch.

1. To create a pull request:

   1.1. Navigate to the main page of your repository.

   1.2. Under your repository name, click **Pull requests**. By default, all
   open pull requests are displayed.

如果在步驟中包含程式碼範例，請確保它們也正確縮排:

  1. 設定您的 Git 典藏庫使用者名稱。

    您可以使用 git config 指令來變更與 Git 提交關聯的名稱。

    git config user.name "Dakota Everson"

編寫步驟的技巧

  • 關於任務名稱，開頭以`原形動詞 <https://en.wikipedia.org/wiki/Infinitive#English>`_亦稱基本形式或`基礎形式 <https://en.wikipedia.org/wiki/English_verbs#Base_form>`_。例如 "連接"、"設定" 或 "建立"，並將標題表述為完整的句子。請勿使用動詞的 -ing 形式，因為此形式較難翻譯。與其說 "Connect"，不如說 "Connect to the VM instance"。

  • 對於每個步驟，您可以選擇性地提供一些關於該任務的背景訊息，以便使用者了解他們即將執行的操作及其原因。繼續以上述範例為例，您可以提供一些建立易於記憶的典藏庫名稱最佳實務建議。

  • 可選地，在說明文字後加入 程式碼範例 或 螢幕截圖，具體取決於您撰寫的操作指南類型。螢幕截圖是展示步驟中提及的特定螢幕區域的絕佳方式。請確保您的程式碼範例能正常運作，並始終保持最新狀態。

  • 在引導使用者完成每個步驟時，請務必提供明確的指導。如果他們需要開啟特定檔案或對話方塊才能完成任務，請先提供相關資訊。

  • 提供範例輸出，例如傳回資料或訊息，以便使用者驗證他們是否正確執行了該步驟。例如，您可以展示在命令列介面 CLI 中輸入命令後，有效且預期的結果會是什麼樣子。

  • 請使用簡單易懂的語言，並在旁邊解釋任何技術術語。

  • 每個步驟只能包含一個操作。

有關編寫步驟的更多技巧，請參閱 編寫程式步驟。

關於 "參見" 部分

在解釋包含多個任務的流程時，您可能會提及與目前任務相關的其他主題，但這並非絕對必要。本節旨在為使用者提供延伸閱讀建議，而不會中斷目前文件的主題。

例如，設定電子郵件用戶端需要有效的電子郵件地址憑證。讀者無需了解如何安裝和運行電子郵件伺服器即可獲得存取權限，儘管了解這些資訊可能很有用。因此，可以將有關執行本機郵件伺服器的文件連結新增至 "參見" 部分。

附加資源

探索其他指南和模板來自 優秀文件計畫。