このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- SciPy
- テクニカル ライター:
- mkg33
- プロジェクト名:
- ユーザー重視のドキュメントと徹底した再構成
- プロジェクトの長さ:
- 標準の期間（3 か月）
プロジェクトの説明
モチベーション:
さまざまなニーズを持つユーザーが簡単にアクセスできるように、既存のドキュメントのリファクタリングに取り組む予定です。言うまでもなく、研究者は高度で微妙な機能に興味を持つ可能性が高いのに対し、専門知識のないユーザーは、手順ガイドや図表を重視します。
私は、個人的および職業上の理由でこのプロジェクトに興味があります。まず、SciPy に多大な貢献をしたいです。なぜなら、私自身の研究が SciPy から大きな恩恵を受けているからです。第二に、他のソフトウェアのドキュメントが不十分な（または不足している）ことに頻繁に遭遇します。徹底的なガイドが提供されれば、どれだけ早くコードの使い方を学ぶことができるかと常に思っています。
目標:
既存の SciPy ドキュメントを、コンテンツとグラフィックの両面で改善することを目指しています。この問題に対する私のアプローチの最も重要な特徴は、ユーザー アンケートの実施と分析です。つまり、さまざまなユーザーがドキュメントに関するニーズを表明できるように、オンラインで簡潔なアンケートを実施します。私は彼らの意見がインスピレーションの源になるべきだと強く信じています（よりユーザー フレンドリーなドキュメントを作成するにはどうすればよいか）。
プロジェクト自体の実現については、最初のフェーズではユーザー調査の設計と分析を行い、現在のドキュメントで気付いたいくつかのスタイルの問題に対処します。たとえば、一貫性の欠如（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 ドキュメントに統合すること（より正確には、その中の多数のハイパーリンクを統合すること）に大きな問題は見当たらないことです。これは、TikZ の画像を HTML に埋め込むためのさまざまなパッケージや修正（TeX4ht など）が存在するためです。
SciPy 内のガイドの今後のメンテナンスについては、Overleaf（コラボレーションを容易にし、即時プレビューを提供）や、私が提供する事前定義済みテンプレートを使用すると簡単に解決できます。基本的に、グラフィック ガイドは互いに大きく異なることはありません。構造、カラーパレット、形状はほぼ不変であるため、後で形状を変更したり、さらにカスタマイズしたりしても問題ありません。
（提案の全文については、共有 GSoD フォルダをご覧ください）。