このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- 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 でサポートし、明確に理解することができます。
API によってフェッチされるレスポンスのタイプ、JSON のタイプ、または API によって返されるその他のタイプの結果について説明します。
さまざまな API ルート、それらのルートとともに送信する必要があるすべてのパラメータ、ヘッダーなど。各 API は、いくつかの言語で記述されたコードサンプルで支援を受けます。コード作成中のリクエストの実行方法については、各 API で発生する可能性のある一般的なエラーコードについても触れておきましょう。
これは、REST API のドキュメントを定義する方法の一般的な考え方です。
プロジェクトのスケジュールは次のとおりです。
8 月 1 日～ 9 月 1 日
私のメンターについて知り、コードベースのさまざまな部分で必要なドキュメントのレベルについてより深く議論し、低レベルのドキュメントと概要レベルのドキュメントについて、それぞれどの程度深く掘り下げるかについて話し合います。また、より適切に文書化できるように、コードベースの理解とコンセプトの学習にもこの時間を使います。
第 1 週と第 2 週
コントリビューター ガイドを更新して拡張します。ソースコードのビルド方法に関するドキュメントを改善します。また、新しいコントリビューターがドキュメントの作成をどのように支援できるかについて、documenters セクションも追加します。さまざまな API ドキュメントについて学習してから、概要から開始して API の認証を追加します。
第 3 ～ 8 週
API のタイプごとに API のルートとレスポンス、コードサンプルを追加します（同じようなタイプの API がある場合もあります）。
第 9 週と第 10 週
リンクを使用して構成する API ドキュメント（長い API ドキュメントのリンク インデックスなど）を追加し、コード セクション、概要、パラメータ、ルート エンドポイントなど、異なる基準でさらに分割します。
最終週
最後の週に、12 週間の文書化期間に行った作業に関する最終報告書を準備する予定です。また、ドキュメントのレビューと最終決定にもこの時間をかけます。