ボケ プロジェクト

このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。

プロジェクトの概要

オープンソースの組織:
ボケ
テクニカル ライター:
vis_verborum
プロジェクト名:
作成、読み取り、共有: Bokeh のドキュメントの最適化
プロジェクト期間:
標準期間（3 か月）

プロジェクトの説明

作成、読み取り、共有: Bokeh のドキュメントを最適化する

1. 概要

Bokeh は、Python でインタラクティブなブラウザベースの可視化を作成するための非常に強力なツールです。かなりのユーザーベース（月間 502,000 件の conda ダウンロード、855,000 の PyPi ダウンロード）と多数のコントリビューター（GitHub の 455 人のコントリビューター）がいます。Bokeh の広範なドキュメントが有機的に成長しているのは当然のことです。そのため、一部のコンテンツは不整合があり、アクセスしづらく、複雑になっています。

Google のドキュメント シーズンは、Bokeh のドキュメントの構造と内容を集中的にレビューして改訂し、ドキュメントと関連するツールとワークフローが将来にわたって有効であることを確認する絶好の機会です。

Python と Sphinx（直近では PyZillow と PyPresseportal）を使用して、オープンソース プロジェクトをコーディングし、文書化しています。しかし、Google の Season of Docs に私が参加しているのは、ジャーナリズムの経歴です。13 年以上は報道機関で働き、何年も管理編集者、デジタル変革の提唱者として働いていました。ジャーナリストとしての業務に加え、新しいデジタル ツールやスタイルガイドの設計とドキュメント化、ニュースルームのスタッフのトレーニングなど、責任が増大しました。

最近ヨーロッパから米国に移住した後、コミュニケーションとコーディングへの情熱を組み合わせた新しい方法を探求することにしました。技術的な文章作成は、ライティングとテクノロジーに関する私のスキルと経験の最適な組み合わせだと感じています。この提案では、Google の Season of Docs を利用して Bokeh のドキュメントを最適化する方法を説明します。ドキュメントの作成とドキュメントへの貢献をより便利にすること、ドキュメントの読み取りをよりわかりやすくすること、ドキュメント内の情報を他のユーザーと共有することを容易にすることにより、最適化を図ります。

2. 現在の状況

Bokeh の公式ドキュメントは、次の主要なユニットで構成されています。

  • ナラティブ ドキュメント: インストール ガイド、ユーザーガイド、デベロッパー ガイド、リリースノート
  • ギャラリーとデモ（ソースコードを含むインタラクティブな例）
  • リファレンス ガイド（docstring に基づくドキュメント）
  • チュートリアル（mybinder.org でホストされている Jupyter ノートブックの広範なコレクション）
  • IDE のドキュメント ストリングとモデルヘルプ
  • プロジェクト リポジトリの例と README

また、Bokeh のサポート フォーラム、Stack Overflow（Bokeh のデベロッパーがユーザーの質問に積極的に回答しています）、Bokeh の Medium ブログでも豊富な情報を入手できます。

ドキュメントのウェブページのほとんどは、Sphinx で作成され、いくつかの標準およびカスタムの Sphinx 拡張機能が使用されています。たとえば、リファレンス ガイドは、「autodoc」などの拡張機能とカスタムの「bokeh_autodoc」を使用して、docstring から生成されます。有機的に成長したドキュメントの性質上、冗長性と不整合があります。

既存のドキュメントを分析した際に最初に気付いたことの一つは、ドキュメント作成に関する明確なスタイル ガイドラインがないことです。Bokeh デベロッパー ガイドには、基本的な手順が記載されています。ただし、このドキュメントにはスタイル、特に docstring を超えたドキュメントに関するガイダンスはあまり含まれていません。その結果、スタイルや構造の問題により、特に新入社員にとってドキュメント内の情報を探すのが難しくなります。

例:

  • 明確で強力な動詞の代わりに、名詞、動名詞、一般的でない単語を使用すると、テキストの一部が不必要に複雑になります。「主な観察事項は、典型的な使い方では、figure() 関数で plot オブジェクトを作成することです」。読みやすくするために言い換えてください。たとえば、「figure() 関数は、プロット オブジェクトの作成に最もよく使用される関数です。」
  • 「次に、果物名要素のリストを x 座標、バーの高さを上の座標として、また、必要に応じて幅などのプロパティを指定して、vbar を呼び出すことができます。」長い文は、短い文または箇条書きのリストに分割する必要があります。文を簡素化することは、失読症のユーザーや英語を母国語としていないユーザーにとって特に役立ちます（問題 #10160 を参照）。
  • 「お客様」と「Google」の使用が統一されておらず、混乱を招き、注意をそらします。「ユースケースに応じて使用できる基本的な方法が 2 つあります」と「個別の呼び出しを使用してすべての年系列をプロットできます」（同じページの 2 つの例）ページによっては、「ユーザーは追加の依存関係をインストールしなければならない場合があります」や「より複雑なレイアウトを作成できます」など、読者への説明が異なる場合もあります。
  • 誤字脱字、不足している単語や余分な単語、文法上の誤りは、読みの流れを中断し、情報の信頼性を損ないます。「Bokeh では基本的な棒グラフを簡単に作成できます」や 「ユーザーガイドのグリフ セクションをご覧ください」など。
  • 構造的な矛盾があると、読者をストレスがたまる可能性があります。たとえば、あるページでは適切なアノテーションが付けられたサンプルがあり、別のページでサンプルの説明が欠けている、などです。

Bokeh のドキュメント ランディング ページは比較的短く、利用可能なすべてのリソースに関する情報は含まれていません（docstring とモデルヘルプ関数の広範なライブラリ、サポート フォーラム、デモ、Medium ブログについては言及されていません）。また、新規ユーザーが Bokeh を使い始めることも難しくなります。

3. 目標

11 週間のドキュメント開発フェーズを最も効率的に活用するため、次の 3 つの要素に焦点を当てます。

3.1. ドキュメントの作成を改善する

Bokeh のドキュメントのほとんどは、新機能やバグ修正のプル リクエストの一部としてドキュメントを追加するコントリビューターによって作成されています。ドキュメントの開発フェーズでは、既存のドキュメントの編集とリファクタリングを行いますが、ドキュメントの作成と維持のためのワークフローを将来に備えて構築することに重点を置きます。コントリビューターが常に高い基準のドキュメントを維持できるように、できるだけ簡単にする必要があります。

そのため、次の 2 つの方法で対応いたします。

  • 既存のデベロッパー ガイドに、実用的でシンプルなスタイル ガイドラインを作成します。これらのガイドラインでは、スタイル、文法、構造について説明します。さらに、Slack などの社内コミュニケーション チャネルを使用して、Bokeh のコントリビューターにスタイル ガイドラインを周知させます。チーム向けに 1 対 1 のトレーニングと Q&A セッションも開催する予定です。
  • コアチームと協力して、ドキュメントの品質管理に最適なツールセットを見つけ、PR（プルリクエスト）と CI（継続的インテグレーション）の既存のワークフローに追加します。チームの要件に応じて、Bokeh のテストスイート、pre-commit 設定、GitHub アクションに pydocstyle、proselint、sphinxcontrib-spelling などのスペルチェック ツールを追加できます。独自のオープンソース プロジェクトの GitHub Actions に、実用的な概念実証を追加しました。

3.2. ドキュメントの読みやすさを改善する

優れたドキュメントの目的は、現在のユーザーと見込みユーザーが正確な情報を簡単に見つけ、その情報をできるだけ効率的に利用できるようにすることです。

テキストのユーザビリティを決定する重要な要素は、そのスタイルと構造です。明確で一貫したスタイルでドキュメントを作成することで、読者は気を散らしたり余計な表現をすることなく、すぐに情報を理解できます。ドキュメントの構造はシンプルでわかりやすく、関連情報をすばやく見つけることができます。

この 2 つの分野に重点を置き、特に新規ユーザーにとっての使いやすさに重点を置きます。その際には、ユーザーガイドを中心に、ナラティブのドキュメントも徹底的に確認します。また、ドキュメントのランディング ページも全面的に改訂し、さまざまな対象ユーザーに明確に対応し、すべてのユーザーが適切なリソースをすばやく見つけられるようにします。

上記のドキュメント作成の改善と同様に、今後の改善と Bokeh のドキュメントの継続的な高水準化の基盤を築くことに注力します。

3.3. ドキュメントの共有を改善

Bokeh に関する議論は、サードパーティ プラットフォームでますます活発になっています。これらのプラットフォームの多くは、Facebook の OpenGraph などのメタデータを使用して、リンクのリッチ プレビューを表示します。OpenGraph は、Facebook、Twitter、LinkedIn、Slack、iMessage などのサービスで使用されます。Bokeh の Discourse フォーラムでも、OpenGraph を使用してリンク プレビューをレンダリングしています。

このテクノロジーを利用するために、問題 #9792 に記載されているとおり、Sphinx で生成された Bokeh のウェブページにメタデータを追加します。最も効率的な方法は、専用の Sphinx 拡張機能を使用することです。数日前、OpenGraph データ用の Sphinx 拡張機能の最初のバージョンが GitHub で公開されました。Bokeh のドキュメントで使えるように、この拡張機能を改善するために、ドキュメント開発フェーズの一部を使用します。

また、独自のオープンソース プロジェクトの 1 つである PyPresseportal で、概念実証を作成して成功させています。この拡張機能は、タイトル、説明、画像、URL などの関連情報を自動的に収集します。次に、この情報を Sphinx によって生成された HTML コードに OpenGraph タグとして挿入します。

この拡張機能の開発の次のステップは、カスタム ディレクティブを導入して OpenGraph メタデータを手動で定義することです（docutil の既存の「meta」ディレクティブに似ています）。自動生成されたメタデータは、手動で入力したデータがない場合のフォールバックとしてのみ使用されます。

構造化データのサポートは非常に複雑であるため、ここでは主に、Bokeh のドキュメントに高品質の OpenGraph メタデータを含めることに焦点を当てます。OpenGraph のサポートに取り組むすべての作業は、同時に構造化データのサポートの基盤を築くことになります。

Sphinx コミュニティと ReadTheDocs コミュニティのメンバーは、OpenGraph と構造化データの拡張機能の開発に関心を示しています（問題 #1758 や #5208 など）。私は、これらのコミュニティと緊密に連携して開発を進めていきます。

4. 成果物

ドキュメント シーズンで提供される成果物は次のとおりです。

  • Bokeh コントリビューター向けのドキュメント スタイル ガイドライン
  • ドキュメントの自動品質管理を組み込んだ PR と CI のワークフローを改訂
  • ユーザーガイドの編集と再構成
  • ドキュメントのランディング ページの改訂
  • ドキュメントのウェブページに OpenGraph メタデータが含まれ、Sphinx 拡張機能が動作している

さらに、個人ウェブサイトや Medium のブログ、または Bokeh の Medium ブログに、Google の Season of Docs にまつわる道のりを記録する「ドキュメントログ」も残します。これは Google へのプロジェクト レポートのベースとしても使用されます。可能な限り、すべての作業を GitHub の問題と pull リクエストの形で透明性を持って行います。

5. タイムライン

コミュニティ ボンディング フェーズ前: 私はすでに Bokeh の GitHub リポジトリに関するいくつかのディスカッションに積極的に参加し、Google の Season of Docs の Bokeh メンターである Bryan Van de Ven 氏と Pavithra Eswaramoorthy 氏と連絡を取り合っています。Bokeh に関する会話には引き続き参加する予定です。また、可視化を構築して公開することで、Bokeh をさらに習得する予定です。

コミュニティの結束強化フェーズ（8 月 17 日～ 9 月 13 日）:

  • コアチームを知り、メンターと交流しながらプロジェクト計画を改良する
  • メンターとの定期的な報告とフィードバックのためのスケジュールとコミュニケーション チャネルを設定する
  • Bokeh の Slack を積極的に活用し、Google's Season of Docs やドキュメント開発フェーズの目標について、関心のあるすべての Bokeh コントリビューターに伝える
  • Bokeh のコントリビューターからフィードバックを収集して、ドキュメント開発フェーズの計画をさらに洗練させる

ドキュメントの開発フェーズ

週 1、9 月 14 日～ 9 月 20 日:

  • ナラティブ ドキュメントの監査と編集を開始する
  • スタイルガイドの下書きを開始

第 2 週（9 月 21 日～ 9 月 27 日）:

  • スタイル ガイドラインの作業を継続
  • ナラティブのドキュメントの編集を続行
  • ドキュメントのランディング ページの全面的な改修を開始

第 3 週（9 月 28 日～ 10 月 4 日）:

  • スタイル ガイドラインを完成させる
  • ドキュメントのランディング ページを完成させる

第 4 週、10/05 ～ 10/11:

  • ナラティブ ドキュメントの編集を完了する
  • PR/CI ワークフローにドキュメント品質管理ツールを統合することについて、Bokeh コアチームと話し合う

第 5 週、10 月 12 日～ 10 月 18 日:

  • Slack で Bokeh の貢献者と Q&A セッションを設定し、スタイルガイドライン、ナラティブ ドキュメントの改善、PR/CI ワークフローを話し合う
  • デプロイ可能な Sphinx 拡張機能への OpenGraph メタデータの既存の概念実証の開発を開始する
  • Bokeh コントリビューターとの Q&A セッションのフィードバックに基づいてスタイル ガイドラインを改訂

第 6 週、10/19 ～ 10/25:

  • PR と CI ワークフローでドキュメント品質管理ツールのテスト開始
  • メタデータ用の Sphinx 拡張機能の開発の継続

第 7 週、10/26 ～ 11/01:

  • Sphinx 拡張機能のテスト
  • Slack で Bokeh コントリビューターとの 2 回目の Q＆A セッション
  • 2 回目の Q&A セッションのフィードバックに基づいて成果物を改訂する

第 8 週、11/02 ～ 11/08:

  • Sphinx 拡張機能をデプロイし、改良されたナラティブ ドキュメントとドキュメント ランディング ページを公開

第 9 週、11 月 9 日～ 11 月 15 日:

  • ドキュメント品質管理ツールを PR および CI ワークフローにデプロイ
  • デベロッパー ガイドを更新して公開し、スタイル ガイドラインと PR および CI ワークフローの追加を含める

第 10 週、11 月 16 日～ 11 月 22 日:

  • 残りのタスクを確定

第 11 週（11 月 23 日～ 11 月 29 日）:

  • プロジェクト レポートの作成を開始する
  • プロジェクト評価の作成を開始する

プロジェクトの最終段階

第 12 週（11 月 30 日～ 12 月 5 日）:

  • プロジェクト レポートを完成させて送信する

第 13 週、12 月 3 日～ 12 月 10 日:

  • プロジェクト評価を確定して提出する

Google の Season of Docs の終了後:

  • 引き続き Bokeh の開発に関わり、Bokeh のドキュメントの作成に取り組んでいきたいと考えています。
  • OpenGraph/構造化データのメタデータ用の Sphinx 拡張機能の開発を継続する予定です。
  • ジャーナリズムのバックグラウンドと既存のネットワークを活かして、データ ジャーナリズムのツールとして Bokeh を宣伝したいと考えています。たとえば、ジャーナリストを対象に Bokeh について執筆したり、ジャーナリスト向けの環境で Bokeh を使用する方法についてカンファレンスで講演したりします。

6. 自己紹介

私は元々ジャーナリストで、テレビ、オンライン、ラジオのニュースの経験があります。テレビやデジタル ニュースのマネージング 編集者やレポーターとして、執筆と編集を長年にわたって経験しています。同時に、デジタル トランスフォーメーションと自動化を推進する複数のプロジェクトにも携わりました。デジタル ツールとワークフロー、デジタル ニュース ブランドのスタイルガイドとコミュニケーション戦略に関する多くのマニュアルを作成しました。また、チームメンバーにこれらのツールの使用方法をトレーニングしました。

私は、コミュニケーションとテクノロジーの融合に常に興味を持っていました。Python でコーディングを学んだことで、まったく新しい世界が開かれました。たとえば、データ ジャーナリズムのデータ分析や可視化を行うことができるようになりました。コードを学ぶことで、ソフトウェア エンジニアと積極的に連携して、ニュースルームのワークフロー用のデジタル ツールを開発することもできました。

前の仕事で書いたマニュアルやドキュメントは残念ながら非公開です。そのため、現在はオープンソース プロジェクトへの参加に注力しています（例については、下記をご覧ください）。テクニカル ライティングの作業では、Google のデベロッパー向けドキュメントのスタイルガイドや Microsoft のスタイルガイドなどのスタイルガイドを参考にしています。GitHub、Slack、Linux を日常的に使用しています。私は、Sphinx、Mypy、Sphinx autodoc などのツールを使用して、ナラティブ ドキュメント、docstring、型ヒントを作成してきました。

現在フリーランスで働いています。私の勤務スケジュールは、ドキュメント開発フェーズ中に Bokeh のドキュメントに週 25 時間ほど取り組むのに必要な柔軟性を提供しています。太平洋時間帯で勤務していますが、チームのスケジュールやニーズに合わせて調整いたします。

7. 最近のオープンソース ドキュメントの例

  • PyZillow: PyZillow は、不動産ウェブサイト Zillow.com の API 用の Python ラッパーです。私は、コードの提供とコード メンテナーの 1 人として活動するだけでなく、完全なドキュメントを作成しました。ナラティブ ドキュメントとモジュール リファレンスには Sphinx を使用しました。コードに追加した docstring に基づいて、Sphinx 拡張機能の autodoc を使用してモジュール参照を作成しました。

  • PyPresseportal: PyPresseportal は、ウェブサイト presseportal.de の API 用の Python ラッパーです。presseportal.de は、ドイツで最大級のプレスリリースと投資家向け発表の配信サイトです。たとえば、ほとんどの警察署と消防署は、このサービスを使用してプレスリリースを配信しています。ジャーナリストとして長年 API を使用していた私は、ウェブサイトの広範なデータリソースに Python オブジェクトとしてアクセスできる Python インターフェースを開発することにしました。コードと Sphinx ベースのドキュメント全体を作成しました。