このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソースの組織:
- Matplotlib
- テクニカル ライター:
- jeromev
- プロジェクト名:
- matplotlib エントリパスの開発
- プロジェクトの長さ:
- 標準の期間（3 か月）
プロジェクトの説明
はじめに
今年の Google Season of Docs の Matplotlib のプロジェクトの提案は、Matplotlib を新規ユーザーに紹介するコンテンツの作成です。Matplotlib エントリパスの開発では、現在のドキュメントとは異なるアプローチを提案しています。私はこの業界に新しく加わったテクニカル ライターですが、教育と教育に関連する分野を専門としています。テクニカル ライティングと教育には、共感を示し、ユーザーが提供されたリソースでタスクを完了できるようにするコンテンツの作成に重点を置いた非常に似通っています。
このコンテキストでは、Matplotlib のドキュメントを改善して、新規ユーザーに共感できるようにするとよいでしょう。現時点では、資料の多くはランダムなデータとラベルのない映像で構成されています。これらは、Matplotlib のビジュアルと機能をすばやく表示するのに適しています。しかし、Matplotlib を初めて使用するユースケースでは、データをビジュアル要素に変換することは困難です。
説明的なアプローチのコンテキストは、この障害の解決策です。実際の例のレンズを通して手順を記述することで、ユーザーが作業する環境を理解していることを証明できます。これにより、目標達成やタスクの完了に関するドキュメントとユーザーの関係が改善されます。
ユーザーには一貫した目的があります。たとえば、靴会社のデータ サイエンティストは、時間の経過に伴うショッピング トレンドを説明するために、顧客データをチームに提示する必要があります。この場合、ユーザーは Matplotlib を操作し、ライブラリ内のツールを利用して、現在のタスクを完了する必要があります。
ドキュメントを補足するコンテキストを追加することで、新規ユーザーがトピックをより理解しやすくなります。ユーザーが導き出した目的は、ドキュメントと並行しています。2017 年のインタビューでリード デベロッパーの Tom Caswell が語ったビジョン「実際に書くことができ、ユーザーに共感できる人が、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 プロジェクトは、意味があり、私が熱心に取り組んでいるイデオロギーでもあると感じています。
利用ガイドの見直しに取り組むにあたり、私のテクニカル ライターの目標は、ユーザーが利用可能な機能に圧倒されずに目的のタスクが達成できるようにサポートすることです。最適なドキュメントは、ユーザーに合わせて継続的に成長し、どのユーザーも自分の解決策にたどり着けるものであるべきです。