このページには、Google シーズンの Google ドキュメントで承認されたテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- SciPy
- テクニカル ライター:
- mkg33
- プロジェクト名:
- ユーザー向けドキュメントと徹底的な再構成
- プロジェクトの期間:
- 標準の長さ（3 か月）
プロジェクトの説明
モチベーション:
さまざまなニーズを持つユーザーが簡単にアクセスできるよう、既存のドキュメントのリファクタリングに取り組む予定です。言うまでもなく、研究者が高度な機能に興味を持つ可能性が高いのは、高度な機能に興味がある可能性が高い一方、経験の浅いユーザーには、手順ガイドや図表が好まれることは言うまでもありません。
私は個人的および仕事上の理由でこのプロジェクトを追求したいと思っています。まず、私の研究は SciPy から大きな恩恵を受けているため、SciPy に多大な貢献をしたいと思っています。第二に、他のソフトウェアではドキュメントが不十分である（または不足している）ことがしばしばあり、詳細なガイドが提供されていれば、ユーザーはどれだけ早くコードの使い方を学ぶことができるのかと常に思っています。
目標:
既存の 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 ドキュメントの統合では、さまざまなパッケージと TikZ 画像を HTML に埋め込むための修正（TeX4ht など）が存在するため、重大な問題を引き起こさないことです。
SciPy 内のガイドの今後のメンテナンスという疑問は、Overleaf（コラボレーションを容易にし、即時プレビューを提供する）や、これから提供する事前定義テンプレートを使用すれば簡単に解決できます。基本的に、グラフィカル ガイドが互いに大きく変わることはあまりありません。構造、カラーパレット、形状は、ほぼ変わらないため、その後の形を変えたりカスタマイズしたりしても問題にはなりません。
（提案の完全版は共有の GSoD フォルダでご覧になれます）。