このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- Matplotlib
- テクニカル ライター:
- jeromev
- プロジェクト名:
- Matplotlib のエントリパスの開発
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
はじめに
今年の Google ドキュメント シーズンに向けて Matplotlib が提案するプロジェクトでは、新規ユーザーに Matplotlib を紹介するコンテンツの作成を取り上げます。「Matplotlib のエントリパスの開発」では、現在のドキュメントの別のアプローチを提案します。業界初のテクニカル ライターですが、バックグラウンドは教育と教育関連分野です。テクニカル ライティングと教育には強い類似点がありますが、これには共感を示し、ユーザーが提供されたリソースを使用してタスクを遂行できるようにするコンテンツの作成に重点が置かれています。
この点において、Matplotlib のドキュメントは新規ユーザーへの共感性を改善することで恩恵を受けます。現時点での資料の大部分は、ランダムなデータとラベルのない画像で構成されています。これらは、Matplotlib のビジュアルや機能をすばやく表示するのに適しています。しかし、Matplotlib の初心者のユースケースでは、データを視覚的に変換することは困難です。
公開アプローチにおけるコンテキストは、この障害の解決策となります。実際の例のレンズを通して手順を記述することで、ユーザーが働く環境を理解していることを示します。これにより、タスクの達成という目標の達成または期待に関するという点で、ドキュメントとユーザーの関係が強化されます。
ユーザーには、一貫した派生目的があります。たとえば、靴会社のデータ サイエンティストが、時間の経過に伴うショッピングの傾向を説明するために、顧客データをチームに提示する必要があります。この場合、ユーザーは Matplotlib の操作方法を学び、ライブラリ内のツールを活用して、目の前のタスクを完了する必要があります。
ドキュメントをサポートする追加のコンテキストがあれば、新規ユーザーはトピックにより識別しやすくなります。ユーザーの派生目的がドキュメントと平行している。リード デベロッパーである Tom Caswell が 2017 年のインタビューで話し合ったビジョンは、「実際に書くことができ、ユーザーに共感できる人が、基本的に 200 ページの『Matplotlib の概要』を執筆し、それがドキュメントのメインのエントリーとなるようにする」というビジョンの実現を目指しています。
解説書の代替アプローチ
現在のドキュメントでは、Matplotlib の機能、つまりユーザーがこのライブラリを使ってできることを具体的に説明しています。たとえば、チュートリアルは多くの場合、基礎となるメソッドの説明を伴わないパターンに従います。
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
多くの場合、プログラミングのドキュメントとサポートに基づいて、ユーザーが自力でコードを実行して何が起きるかを理解することをおすすめします。プログラミングの考え方はトピックに対するユーザーの理解を向上させますが、変革の習得には補足的なコンテンツはほとんどありません。ドキュメントに限りがあるため、困難な作業になることがあります。
図や画像などを追加すると、新たな学習機会を生み出すのに役立ちます。以下の構造は、新しいコンテンツのテンプレートとしても役立ちます。また、テキスト以外の画像やグラフィックを追加する際には、コールアウトやコーチマークなどの機能が役立ちます。コードがどこでどのように変換されたかを示さずに、画像が操作しにくい場合があります。トピックに対する理解を深めるための強力な視覚的要素が不足していると思います。
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
この代わりの方法である、文書化に説明書を使用するという方法には、大きな可能性が秘められています。変換に関するさまざまな概念を目にすることで、データを可視化する開発の基本戦略をより深く理解できるようになるでしょう。この知識は、実際のユースケースに基づいた例示されているように、ユーザーがイノベーションを起こし、機能を活用するのに役立ちます。
Matplotlib の人気が高まる中、使いやすさと親しみやすさの一貫性は、この図書館の評判の証です。これらの特性は、コード内だけでなくドキュメント内でも表面化できるパターンや一般的な戦略を示すのに有用です。利用が増え、リソースが拡大していることが明白なように、matplotlib のプログラミングが単純かつ標準的なものであれば、技術ドキュメントでもその傾向があります。
ユーザーが問題に直面したときに、解決するために検索を使用するのが一般的です。ナビゲーションの主要な方法として検索を利用するのではなく、ドキュメント内でユーザーに独自のカリキュラムを作成してもらうほうが、より影響力があるかもしれません。つまり、ユーザーは問題の解決策を検索して、別の問題に遭遇したときや追加情報が必要になったときに、埋め込みリンクや詳細なリンクを活用することができます。
これには、組織システムにボトムアップ アーキテクチャが含まれます。Matplotlib のすべてのトピックについて、テーマのアフィニティと情報トピックへのリンクの豊富なネットワークは、堅牢なネットワークの構築に役立ちます。このネットワーク全体で、ユーザーはトピックに移動し、そのトピックに関連するより多くの情報を探索する際に、ドキュメントを引き続き使用する可能性が高くなります。
障害
これほど包括的で詳細なプロジェクトには、常に課題が伴います。業界での新人テクニカル ライターとして、Sphinx と ReST を使用してドキュメントを作成した経験は限られています。Matplotlib と Git については初心者でもあります。これら 4 つのシステムに取り組み、コラボレーションや研究に使い慣れるには時間がかかるでしょう。初歩的な学習計画に必要な基盤を構築するために、コミュニティの絆を深める段階とそれ以前に、時間を委任する必要があります。この期間中、コンセプトや基本事項に問題がある場合は、コミュニティに問い合わせてサポートを得る必要があります。
異なるタイムゾーンやオンライン プラットフォーム間での共同作業を調整する場合も、ある程度の調整が必要になります。コミュニケーションの手段は、業界全体で多種多様です。したがって、あらゆるメディアでアクセスしやすく親しみやすいものにすることが重要です。全体を通してさまざまな期待値に優先順位を付けて、透明性を確保する。業界でこのような仕事に取りかかり始めたばかりですが、責任を果たし、フィードバックや批判を受け入れることに注力しています。こうした資質は、どの分野においても価値があると思います。
また、ユーザビリティ テストの強化は、Matplotlib の導入パスにメリットをもたらすと考えられるドキュメントのセクションです。コンテンツのユーザビリティに関するアンケートは、ユーザーのプロフィール（ペルソナ）を提供することを目的としています。ユーザー エクスペリエンス、業界、トラブルシューティング履歴などの情報は貴重です。これらの要素によって、医療処置の背後にある言語が形成されます。文章が読者のレベルのレベルに到達すれば、単に教育的なものとしてではなく、より成熟したコンテンツになっていきます。
ユーザビリティ テストの継続的な実施が、大きな苦労となることがよくあります。コンテンツ開発において、たとえ 1 回のテストをしても、それはごく普通のことです。定期的なユーザビリティ テストによって、コンテンツのナラティブを推進できる。スケジュールを設定したり、Matplotlib コミュニティとユーザビリティ テストを繰り返し行ったりしたいと考えています。
まとめ
自由時間には Python と Matplotlib を使っても多少の経験があります。この数か月間、私は現在のドキュメントのサポートと私自身の好奇心のおかげで、独学で学びました。その頃、私には動画やメンターが少しだけありました。学ぶべきことはまだたくさんあり、興味のあるプログラミングのカリキュラムを独自に構築する中で、さらなる改善の余地がまだ残っています。
Matplotlib とコミュニティが GSoD に求めるアイデアを見たので、テクニカル ライターとしてのスキルを向上させ、舞台裏の人たちからより多くのことを学ぶ機会を得ることは、成長するうえで素晴らしい体験だと感じています。この Matplotlib プロジェクトは有意義であると同時に、イデオロギーの分野でも情熱を注いでいるものだと感じています。
使用ガイドの全面的な見直しに取り組む中で、テクニカル ライターとしての目標は、ユーザーが圧倒されることなく目的のタスクを完了できるようにすることです。最良のドキュメントは、成長し続け、ユーザーに適応し、あらゆるユーザーが独自のソリューションを探求できるようになると信じています。