このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- ScummVM
- テクニカル ライター:
- b-gent
- プロジェクト名:
- Doxygen でソースコードのドキュメントを改善する
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
現在の ScummVM API（ソースコード）のドキュメントは、https://doxygen.scummvm.org/modules.html で公開されています。
残念ながら、多くの分野で採用されていない。
1）実質的に構造はなく、すべての情報が同じレベルに配置されています。
2）C++ 要素が、まったくドキュメント化されていない一部の要素と矛盾してドキュメント化されています。このことは、組織が主な問題の一つとして言及しています。
3）古いコンテンツやサポートが終了したコンテンツが引き続き出力に表示される。
4）酸素タグの使用言語と使用方法は、より一貫性を持たせる必要がある。このための一連のルールが必要です。このプロジェクトの今後のドキュメント スタイルガイドの基礎となる可能性があります。
5）このページで使われている doxygen CSS は、ScummVM のウェブサイト（https://www.scummvm.org）に近づけるために改善できます。
これらの問題はすべて、「ドキュメント シーズン」プロジェクト中に解決できます。
このシーズンのドキュメント アプリケーションには、私が提案する改善点を示すためにプロジェクト内で開いた PR 案が付属しています: https://github.com/scummvm/scummvm/pull/2361 含まれる内容の詳細および差分の確認については、そちらの説明をご覧ください。
PR に含まれるのはおおむね次の内容です。
1）現在、新たなコントリビューターとなる可能性のあるユーザー、、そして現在の API ドキュメントを見るすべての人にとって最もわかりにくいのは、構造が不足していることです。構造化 API ドキュメントを導入することで、ドキュメント セットの読みやすさ、見つけやすさ、ひいてはユーザビリティが向上します。そのため、私の PR は「common」フォルダ内のすべてのヘッダー ファイルに doxygen グループを導入しています。この新しい構造では、たとえば OS 関連の API のドキュメントを見つけたい場合に、ナビゲーションで簡単に見つけることができます。
2）このドキュメントの作成を可能にするために、新しい doxygen 構成ファイルが設定されている。
3）ドキュメント セット全体で使用されるすべてのリンクを単一ソース化できる「links.doxyfile」ファイル。酸素を扱う際に便利なメカニズムです。
4）改変された Doxygen CSS。これは現在、別のオープンソース プロジェクトから取得したものであり、出発点にすぎません。理想的には、doxygen ページのデザインは、ScummVM のウェブページとほぼ一致する必要があります。
PR でカバーされていませんが、コンテンツ自体は対応する必要があります。具体的には、ドキュメント化されていないコードの重要な部分、十分にドキュメント化されていない部分、ドキュメントから削除すべき古いコード部分を特定することです。私はプロジェクトに携わったことがないので、そのためにはメンターの指導が必要になります。
もちろん、PR で挙げたものを実装するかどうかは、組織と協議する必要があります。行動は言葉よりも雄弁だと考えたので、アプリケーションで説明するだけでなく、何ができるかを示すことにしました。
組織はこのプロジェクトについて、以下の大まかなタイムラインを提供している。 メインタスク 第 0 週（9/14 より前） 提案のディスカッションとレビュー 第 1 週（9/14）Doxygen ビルドのセットアップ 第 2 週（9/21）Doxygen スキンの更新（低優先度） 第 3 週（第 9/28 週）共通コード - OSystem、FS、データ
私から提案する変更点は、先に述べたような構造に取り組むことだけです。これは、第 1 週と第 2 週に、doxygen ビルドのセットアップ（ほぼすでに完了しています）と Doxygen スキンの更新と一緒に行うことができます。その後、メンターと一緒にさまざまな分野を 1 つずつ見ていき、問題を特定し、Doxygen のドキュメントを改善することが最も理にかなっていることに同意します。
これは標準の長さのプロジェクトですが、GSoD プロジェクトの終了後には、API ドキュメントに関して他にも改善の余地があると思います。たとえば、ドキュメント スタイルガイドを作成し、それを Wiki に追加して、コントリビューターが追加するコードをどのように文書化すべきかを認識できるようにします。
GSoD が終了した後も、このような作業についてサポートさせていただきます。ScummVM には、品質と利便性の高い API ドキュメントを確実にしてくれるテクニカル ライターがいるだろうと思います。また、プラグインの操作方法に関するガイドの作成など、今後お手伝いできるドキュメント プロジェクトが他にもあるようです。