このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- ジュリア語
- テクニカル ライター:
- mkg33
- プロジェクト名:
- 科学的機械学習に関する統一ドキュメント
- プロジェクトの長さ:
- 長期実行（5 か月）
プロジェクトの説明
私は SciML 組織の統合に取り組んでいきたいと考えています。この分野には改善の余地が多くあり、このプロジェクトの完了は、Julia のプログラマーと SciML の積極的な貢献者/メンテナンス担当者の双方に直ちにメリットをもたらすことでしょう。SciML 全体に散らばっているパッケージには、非常に便利なツールがいくつかありますが、ユーザーがパッケージを見つけて、直面している問題に適用できなかったという理由だけで、（特に新規ユーザーが）気付かれない危険が常に存在します。
このパッケージの主な目的は、幅広いプログラマ（初心者からエキスパートまで）にリーチすることであるため、これはかなり不便です。上記の状況を回避するために、SciML ドキュメントの「フロントページ」を徹底的に改訂し、ユーザーが関連パッケージをブラウジングして、成長するエコシステムを探索できるハブを作成することを提案します。また、経験豊富なユーザーにとっては、作業効率の向上につながる貴重な参照ポイントにもなります。
まず、すべての個別パッケージの既存のドキュメントは、最も基本的なスタイルの問題（スペル、句読点、文法など）について改訂する必要があります。スタイルの整合性を確保するために、SciML には具体的なスタイルガイドが必要です（後から変更を加えたり、今後の参照に使用したりするために不可欠です）。ゼロから始めるのは時間の無駄です。代わりに、既存の Julia 規則に基づいて、SciML 固有の問題向けの新しい全体を含める必要があります。
スタイルガイドが完成したら、プロジェクトの第 2 フェーズで現在のドキュメントを改訂する予定です。これにより、ドキュメントがよりプロフェッショナルで安定した印象になります。このタスクへのアプローチを示すプルリクエストをすでにいくつか作成しています。このフェーズでは、効率的な引用システムを考案（実装）することも検討します。最初のタスクは、古い引用ページを更新することです。
3 つ目のフェーズは、最も重要なフェーズで、SciML ロードマップの設計を行います。このフェーズでは、分散しているパッケージ間の相互作用を重視します。2 つのパッケージ間の結合が強いほど（問題またはコード自体に関して）、[関連情報] リストに近い位置に表示されます。2 つのレコメンデーション キーを作成することを提案します。1 つはコードの類似性用、もう 1 つは問題の類似性用です。このようにして、ユーザーはそれぞれのリポジトリやドキュメントを面倒な目で見て回るよりもはるかに速く、役に立つ可能性のある他のパッケージを特定できます。パッケージ間の考えられる接続をすべて一覧表示するのではなく、大きなパッケージに焦点を当て、小さなパッケージとのリンクを提示するようにします（この方法は、別のパッケージとの接続を指摘する必要があるチュートリアルの更新にも適用されます）。このアプローチにより、「関連情報」リストに、パッケージの組み合わせを網羅的に列挙することなく、有益な情報を含めることができます。