このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- Julia 言語
- テクニカル ライター:
- mkg33
- プロジェクト名:
- 科学的 ML の統合ドキュメント
- プロジェクトの期間:
- 長時間（5 か月）
プロジェクトの説明
SciML 組織の統合に取り組みたいと思っています。この分野には改善の余地が多く、このプロジェクトの完了は間違いなく、Julia のプログラマーと SciML の積極的な貢献/保守者の両方にすぐに利益をもたらすでしょう。SciML に散在するパッケージには実に便利なツールがいくつか用意されていますが、単にユーザーがパッケージを見つけて目指している問題に適用できないという理由だけで、（特に初めて利用するユーザーにとって）見過ごされてしまう危険性があります。
このパッケージの主な目的は幅広いプログラマー（初心者からエキスパートまで）にリーチすることなので、これはかなり不満です。このような状況を避けるために、SciML ドキュメントの「フロントページ」を全面的に改訂し、ユーザーが関連パッケージを閲覧したり、拡大するエコシステムを探索したりするために使用できる一種のハブを作成することを提案します。また、経験豊富なユーザーにとって貴重な参照ポイントにもなり、作業の効率化に役立ちます。
まず、すべての個別パッケージの既存のドキュメントは、最も基本的なスタイルの問題（スペル、句読点、文法など）に関して修正が必要です。スタイルの一貫性を確保するために、SciML には具体的なスタイルガイドが必要です（遡及的な変更を行う場合や将来の参照のために不可欠です）。ゼロから始めるのは時間の無駄になります。むしろ、既存の Julia の規則に基づいて、SciML 固有の問題の全体を網羅する必要があります。
スタイルガイドが完成したら、プロジェクトの第 2 フェーズで現在のドキュメントを改訂する予定です。よりプロフェッショナルで安定した印象のドキュメントになります。私はすでに、このタスクへのアプローチを示す pull リクエストをいくつか作成しました。このフェーズでは、効率的な引用システムの考案（と実装）も予定しています。最初のステップとして、古い引用ページを更新します。
おそらく最も重要な 3 番目のフェーズは、SciML ロードマップの設計です。このロードマップでは、分散したパッケージ間の相互作用を強調します。問題またはコード自体に関して、2 つのパッケージ間の関連性が強いほど、「関連項目」リストに載っているほどよいでしょう。私は 2 つのレコメンデーション キーを作成することを提案します。コードの類似性と問題の類似性です。そうすれば、ユーザーはそれぞれのリポジトリやドキュメントを面倒にブラウジングするよりもはるかに速く、他の潜在的に有用なパッケージを特定できます。パッケージ間で可能な接続をすべて列挙するのではなく、大きい方のパッケージを重視し、小さいパッケージでのリンクを提示するようにします（この方法は、別のパッケージとの接続を指摘すべきチュートリアルの更新にも拡張されます）。このアプローチにより、パッケージの組み合わせをすべて列挙するのではなく、「関連項目」リストが有益であることが保証されます。