このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- SymPy
- テクニカル ライター:
- Soumi7
- プロジェクト名:
- docstring 間の一貫性 - Sympy ドキュメント
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
要約 :
「Current State of Sympy」ドキュメントとこれまでの作業 :
SymPy の公式スタイルガイドを作成する作業はこれで完了です。
Lauren Glattly の GSoD プロジェクトは、SymPy の docstring のスタイルガイドを作成しました。SymPy Documentation Style Guide を参照してください。
Special サブモジュールと Solrs.py ファイルの docstring が、新しいスタイルガイドのガイドラインに一貫して沿うように編集されました。
コードベースの他のすべての docstring も、新しいスタイルガイドに従って編集する必要があります。
提案する課題 :
SymPy のほとんどの docstring は最新のスタイルガイドに従っていません。このプロジェクトの目標は、このガイドに沿って SymPy 全体の docstring を更新することです。
メンターとプロジェクトについて話し合いました。このディスカッションへのリンクはこちらです。
最新のスタイルガイドに準拠するために sympy のコードベース全体で docstring を編集する作業は大変な作業であり、プロジェクトはそれに限定すべきであると判断されました。
このプロジェクトでは、新しいガイドを実装して既存の docstring を更新すると同時に、言語の使用や用語などの他の不整合を収集して対処します。
既存のサブセクションの順序は、後で、または個別のタスクとして、変更または決定できます。
パラメータに異なる値が渡されたときの結果の違いを説明するために、パラメータ セクションに加えて例を追加します。
「問題点」と「問題点」のセクションに、難しい例をさらに追加してください。
投稿: - #17887 : 問題 #17887 に対応: 特別なサブモジュールに欠落している docstring セクションを追加。L が編集した特殊サブモジュールの関数に、欠落しているパラメータと例のセクションを追加しました。最新のスタイルガイドに従い、今後の docstring のモデルとして活躍。
私のマージされた PR へのリンクはこちらです：https://github.com/sympy/sympy/pull/19334
- #19591 : 問題 #19591 は、ドキュメント スタイル ガイドを追跡します。最新のスタイルガイドに沿って core.sympify docstring を編集するための PR を追加しました。さまざまなパラメータの使用方法について、構造化された説明と例を追加しました。
PR へのリンクはこちら: https://github.com/sympy/sympy/pull/19613
プロジェクトの目標
スケジュール 8 月 17 日まで :
- 組織への貢献を継続します。
- ユーザー ドキュメントと sympy の現行バージョンに精通する。
- プロジェクトを実施する際に役立つ手法やスキルを学びます。
コミュニティの絆（2020 年 8 月 17 日～ 9 月 13 日）
- コミュニケーション チャネルと時間（時差により）を用意する。
- 目標を絞り込んで、双方に期待値を設定する。
- モジュールの更新順序についての説明。
- 編集モジュールの順序を確定して、最新の docstring スタイルガイドに従うようにします。
提出期間（2020 年 9 月 14 日～ 2020 年 11 月 30 日）
毎週、達成目標を設定します。可能であれば、1 週間に 1 回以上のモジュールまたはサブモジュールの docstring の更新を完了します。
これらすべてのモジュールでの主な目標は、欠落しているセクションを追加し、最新のスタイルガイドに沿って docstring を再構築することです。これには、パラメータにさまざまな値を渡したときに得られるさまざまな結果のデモが含まれます。難しい出力はすべて、問題と注意点のセクションに追加します。
第 1 週（9 月 14 日～ 9 月 21 日）: コア
第 2 週（9 月 22 日～ 9 月 29 日） : 機能 : サブモジュールの組み合わせ
第 3 週（9 月 30 日～ 10 月 6 日）: 関数
第 4 週（10 月 7 日～ 10 月 14 日）: 簡素化、暗号
第 5 週（10 月 15 日～ 10 月 21 日）：ディオファンチン
第 6 週（10 月 22 日～ 10 月 29 日）: ホロノミック :オペレーションのサブモジュール
第 7 週（10 月 30 日～ 11 月 7 日）: 積分モジュール（integrals.integrals）、マイジャー G 関数を使用した積分の計算
第 8 週（11 月 8 日～ 11 月 15 日）: 物理学、カテゴリモジュールの最後に関数、コード生成モジュール、サブモジュールスペシャル
第 9 週（11 月 16 日～ 11 月 23 日）: 物理学、カテゴリモジュールの最後に関数、コード生成モジュール、サブモジュールスペシャル
第 10 週（11 月 24 日～ 11 月 30 日）: 「問題点と注意点」セクション
2020 年 11 月 30 日～ 12 月 5 日 18:00（UTC）: プロジェクト最終提出および報告書作成
2020 年 12 月 3 日～ 10 日 18:00（UTC）: プロジェクトの成功とメンターのサポート経験の提出
ここで紹介するモジュールの順序は、メンターとの話し合いを重ねた後で変更できます。
メンターからすすめられているように、まずは更新しやすいモジュールから更新することに重点を置き、次に複雑なモジュールに進みます。
私がこのプロジェクトの適任者である理由
私自身がこのプロジェクトの適任者だと思っています。過去にコンピュータ サイエンス分野でのテクニカル ライティングの経験があり、git と GitHub にも精通しているからです。
私は PR を送信して sympy の最新のスタイルガイドにドキュメントを更新したことで、正常に統合されたことから、ワークフローに自信を持ち、定期的に投稿を行ってくれました。
寄付を始めた当初、いくつかのエラーに直面しました。ようやく、毎回テストを実行してドキュメントを作成することに慣れてから、変更を commit できるようになりました。これは非常に重要な作業だからです。
私はこのプロジェクトにも無理なく参加でき、楽しみにしています。