このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- SciPy
- テクニカル ライター:
- mkg33
- プロジェクト名:
- ユーザー指向のドキュメントと全面的な再構築
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
モチベーション:
既存のドキュメントのリファクタリングにより、さまざまなニーズを持つユーザーが簡単にアクセスできるようにするつもりです。言うまでもなく、研究者は高度な機能や機能に関心を持つ可能性が高い一方、予備知識のないユーザーには手順ガイドや図表が好まれます。
個人的、職業的な理由でこのプロジェクトを進めることに興味があります。まず、自分の研究は SciPy から多大な恩恵を受けたため、SciPy に多大な貢献をしたいと考えています。2 つ目の理由として、他のソフトウェアでは不十分なドキュメント（または不足している）がしばしばあり、ユーザーは詳細なガイドが提供されていれば、コードの使い方をどれほど早く学ぶことができるのだろうかといつも思っています。
目標:
私は、既存の SciPy ドキュメントの内容面とグラフィック面の両方を改善することを目指しています。この問題に対する私のアプローチで最も重要な機能は、ユーザー アンケートの導入と分析です。つまり、さまざまなユーザーがドキュメントに関するニーズを声に出せるようにオンラインで実施される簡潔なアンケートです。意見がインスピレーションの源になると強く信じています（もっとユーザー フレンドリーなドキュメントを作成するために他に何かできる方法はありますか？）
プロジェクト自体の実現に関しては、第 1 フェーズとして、ユーザー アンケートを設計、分析するとともに、現在のドキュメントで発見したスタイル上のいくつかの問題に取り組みます。たとえば、一貫性の欠如（例: 2 次元配列と並んで 2 次元配列が出現する）、書き直すべき複雑な文、特定のサブページ内のアルファベット順ではないなどです。第 2 フェーズでは、（アンケート結果やその他のコミュニティのリクエストに基づく）関連トピックへのハイパーリンクを含むグラフィカル ガイドの導入に重点を置きます。長期的には、さまざまなタイプのユーザーに合わせて満足のいくドキュメントを作成したいと考えています。さらに、チュートリアルの言語的、構造的ともに一貫性を持たせるよう努めます。最後に大事なこととして、（現在のコミュニティのニーズに基づいて）新しいチュートリアルを作成することを目指しています。
ユーザー アンケート:
ユーザー アンケートに関しては、いくつかの理由から Google フォームの使用をおすすめします。まず、Google フォームは無料で機能性が無制限（回答者数、質問数など）、魅力的なビジュアル フォーム、非常に便利なアンケート オプション（カスタマイズ可能な線形目盛、チェックボックス、多肢選択式など）を備えており、最も重要な点として、統計分析のために結果を簡単にエクスポートできる点が挙げられます。オンライン調査によると、現時点では Google フォームが無料のアンケート調査に最も適しています。Google が運営する取り組みでは、Google プロダクトを使用した方がよいかもしれません。
サンプルの質問を含む予備アンケートを作成しました（https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform）。最終版の設問数は 10 ～ 15 問にすることをおすすめします。具体的な結果を得るには、多肢選択式の質問、線形段階、数個のチェックボックスを優先的に使用することをおすすめします。ただし、線形目盛は全スペクトルを再現することはできません（混乱を招くだけで、結果が大きくばらつきやすくなります）。自由形式の質問は 2 つまでにしなければなりません。そうしないと、結果が大きく分散し、まったく役に立たなくなります。データをエクスポートして統計ソフトウェアで自動的に分析できるため、非常に多くの回答であっても問題にはならないと考えています。回答数が非常に多いと仮定すると、自由回答形式の質問の分析には少し時間がかかるかもしれませんが、圧倒されるわけではないと思います。平均的なユーザーがドキュメントの状態についてエッセイを書くことはまずありません。最悪のケースでは、一部の回答を将来の分析用に単に保存しておくこともできます。
グラフィカル ガイド:
（ナビゲーション ツールとして機能することを意図した）グラフィカル ガイドの私のビジョンは、（ほとんどの）人間は純粋なテキストベースの情報よりも単純な視覚的構造を処理する方が優れているという一般的な前提に基づいています。さらに、興味の対象が似ているトピックを線で結んだテーマ別の図は、経験の浅いユーザーだけでなく、間違いなく非常に価値のあるアセットです。
実装の詳細に関しては、TikZ パッケージの使用をおすすめします。何よりもまず、このツールは強力なツールであり、近いうちに廃止される可能性は低いです。また、品質の高い出力が提供され、非常に確固たるドキュメントがあり、TeX StackExchange やその他のメインストリーム フォーラムで頻繁に取り上げられているトピックです。最も重要な点は、TikZ ファイル（より正確には、その中の多くのハイパーリンク）と HTML ドキュメントの統合では、さまざまなパッケージが存在することや、HTML に TikZ 画像を埋め込むための修正（TeX4ht など）が存在するため、大きな問題は生じないように思われることです。
SciPy 内のガイドの今後のメンテナンスという疑問は、オーバーリーフ（コラボレーションを促進し、即時プレビューを提供）や提供する事前定義テンプレートを使用すれば簡単に解決できます。基本的に、グラフィカル ガイドが互いに大きく異なることはほとんどありません。構造、カラーパレット、シェイプはほぼ一定であるため、その後の形を変えたり、カスタマイズしたりしても問題はありません。
（提案の完全版は共有 GSoD フォルダでご覧いただけます）。