このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- OpenMRS.org
- テクニカル ライター:
- batbrain7
- プロジェクト名:
- OpenMRS REST API のドキュメント
- プロジェクトの長さ:
- 標準の期間（3 か月）
プロジェクトの説明
提案内容はいくつかのセクションに分けて、Google Maps API のドキュメントや GitHub API のドキュメントのような流れに沿って説明します。
これらの方法以外にも、realworld.io による API ドキュメントの README 構造（https://github.com/gothinkster/realworld/tree/master/api）を提案します。
個人的には、このドキュメントは非常にわかりやすく、使いやすいと感じました。
提案は主に次の 3 つのセクションで構成されます。
API の概要、OpenMRS の概要、API の使用方法、その後の内容について説明します。
API リクエストを行うために一般的に必要な API キーと認証を取得する方法。ここでは、API に存在する認証の種類、API に存在する必要があるキーと値、その部分のキーに対応して受け入れられる値の種類の例を紹介します。どの言語のコードサンプルでも、ヘッダー、レスポンス形式、その他のクエリ パラメータの記述方法をわかりやすく説明できます。
API によって取得されるレスポンスのタイプ、JSON のタイプ、または API から返されるその他の結果のタイプを記載します。
さまざまな API ルートと、それらとともに送信する必要があるすべてのパラメータ、ヘッダーなど。各 API には、コードの作成中にリクエストを行う方法を説明する、複数の言語のコードサンプルが用意されています。また、各 API で発生する可能性のある一般的なエラーコードについても説明する必要があります。
これは、REST API のドキュメントがどのように定義されるかについての一般的な考え方です。
プロジェクトのスケジュールは次のとおりです。
8 月 1 日～ 9 月 1 日
メンターを知り、コードベースのさまざまな部分で必要なドキュメントのレベルについて詳しく話し合い、詳細なドキュメントと概要的なドキュメントのどちらに重点を置くかについて話し合います。また、この期間を利用してコードベースを理解し、概念を学習して、より適切に文書化できるようにします。
第 1 週と第 2 週
コントリビューター ガイドを更新して拡張します。ソースコードをビルドする方法に関するドキュメントを改善します。また、新しいコントリビューターがドキュメント作成にどのように貢献できるかについて、ドキュメント作成者向けのセクションも追加します。さまざまな API のドキュメントを調べ、まず概要を確認してから、API の認証を追加します。
第 3 ～ 8 週
API のルートとレスポンスを追加し、各タイプの API のコードサンプルも追加します（類似のタイプの API が存在する場合があります）。
9 週目と 10 週目
リンクを使用して API ドキュメントの構造を追加します。長い API ドキュメントの場合はリンクされたインデックスを追加し、コードセクション、概要、パラメータ、ルート エンドポイントなど、別の基準でさらに分割します。
最終週
最終週は、12 週間の文書化期間中に行った作業の最終報告書を準備します。また、この期間を利用してドキュメントを確認して確定します。