OpenMRS.org 專案

本頁將詳細說明 Google Season of Docs 接受的技術文件寫作專案。

專案摘要

開放原始碼組織：
OpenMRS.org
技術撰稿人：
batbrain7
專案名稱：
OpenMRS REST API 說明文件
專案長度：
標準長度 (3 個月)

Project description

我會將提案分成不同部分，並按照 Google 地圖 API 說明文件和 GitHub API 說明文件的流程進行。

除了這些之外，我也想為 realworld.io 完成的 API 說明文件提出一個 readme 結構：https://github.com/gothinkster/realworld/tree/master/api

我個人認為這份說明文件非常容易理解和使用。

我的提案主要分為 3 個部分：

  1. 這個部分會快速介紹 API、OpenMRS 和 API 的使用方式，以及之後的所有內容。

  2. 如何取得 API 金鑰，以及一般來說，發出 API 要求時所需的驗證。這會包含 API 中出現的驗證類型、需要提供的鍵和值，以及對應於該部分的值類型範例。任何語言的程式碼範例都能協助並清除如何在 API 中編寫標頭與回應格式和其他查詢參數。

  3. 請提及 API 擷取的回應類型、JSON 類型或 API 傳回的任何其他類型結果。

  4. 不同的 API 路徑，以及需要與這些路徑一起傳送的所有參數、標頭和其他內容。每個 API 都會提供多種語言的程式碼範例，說明如何在編寫程式碼時提出要求，此外，也應提及每個 API 可能遇到的一般錯誤代碼。

這是 REST API 說明文件的一般定義方式。

專案的時間表如下：

8 月 1 日至 9 月 1 日

熟悉我的導師，並深入討論程式碼庫的不同部分所需的說明文件等級，以及討論低階和高階說明文件的深入程度。我也會利用這段時間瞭解程式碼庫，並研究相關概念，以便進一步撰寫說明文件。

第 1 週和第 2 週

我會更新並補充貢獻者指南。我會改善說明文件，說明如何建構原始碼。我也會新增「文件編寫者」專區，說明新貢獻者如何協助編寫說明文件。我將研究不同的 API 說明文件，並從介紹開始，新增 API 的驗證機制。

第 3 到 8 週

我會為每種 API 類型新增 API 路徑和回應，以及一些程式碼範例 (可能會有類似類型的 API)。

第 9 週和第 10 週

使用連結新增 API 說明文件結構，例如適用於較長的 API 說明文件的連結索引，然後以不同方式進一步劃分，例如程式碼區段、總覽、參數、根端點。

最後一週

我會在最後一週準備最終報告，說明在 12 週的文件撰寫期間完成的工作。我也會利用這段時間審查並完成相關文件。