ボケ プロジェクト

このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。

プロジェクトの概要

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

プロジェクトの説明

作成、閲覧、共有: Bokeh ドキュメントの最適化

1. 抽象化

Bokeh は、Python でインタラクティブなブラウザベースのビジュアリゼーションを作成するための非常に強力なツールです。大規模なユーザーベース（月間 50 万 2,000 件の Conda ダウンロード、855,000 PyPi ダウンロード）と多数のコントリビューター（GitHub には 455 名のコントリビューター）がいます。Bokeh の膨大なドキュメントが有機的に増えているのは、当然のことです。そのため場所ごとに一貫性がなく、アクセスしにくく、入り組んだ状態になっています。

Google の「ドキュメント シーズン」は、Bokeh のドキュメントの構成と内容の集中的な見直しと修正を行うまたとない機会です。また、将来を見据えたドキュメントとその関連ツールやワークフローを確実に提供することもできます。

Python と Sphinx を使用してオープンソース プロジェクトをコーディングし、ドキュメントを作成しました（直近では PyZillow と PyPresseportal）。しかし、私が Google の Google ドキュメント シーズンに初めて参加した理由は、ジャーナリズムの経歴があるからです。ニュース編集局に 13 年以上携わり、編集長やデジタル変革の推進者として長年務めてきました。ジャーナリズムの業務以外に、新しいデジタルツールやスタイルガイドの設計と文書化、ニュースルーム スタッフのトレーニングなど、これまで以上に責任を担ってきました。

最近ヨーロッパから米国に転居した後、コミュニケーションとコーディングへの情熱を集約する新しい方法を模索することにしました。私は、ライティングとテクノロジーのスキルと経験の最適な組み合わせは、テクニカル ライティングであることがわかりました。この提案では、Google の Google ドキュメント シーズンを活用して Bokeh のドキュメントを最適化する方法を紹介します。ドキュメントの作成と投稿をより便利なものにし、ドキュメントを読みやすくしたり、ドキュメント内の情報を共有しやすくしたりすることで、より便利なものにします。

2. 現状

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

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

さらに、Bokeh サポート フォーラムや Stack Overflow で、Bokeh のデベロッパーがユーザーの質問に積極的に回答しているほか、Bokeh の Medium ブログでも多くの情報が提供されています。

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

既存のドキュメントを分析したときに最初に気づいたことの 1 つは、ドキュメント作成に関する明確なスタイル ガイドラインがないことでした。Bokeh デベロッパー ガイドには、基本的な手順が記載されています。ただし、このドキュメントにはスタイルに関するガイダンス、特に docstring を超えるドキュメントに関するガイダンスはあまり含まれていません。その結果、ドキュメント内の情報にアクセスすることが、特に初めて利用する人にとっては、文体や構造上の問題によりさらに困難になります。

例:

  • 明確で力強い動詞の代わりに、名詞、動名詞、一般的でない単語を使用すると、テキストの一部が不必要に複雑になります。「主な所見は、fig() 関数を使用してプロット オブジェクトを作成することです」。読みやすくするために言い換えてください。例:「fig() 関数は、プロット オブジェクトの作成で最もよく使用される関数」です。
  • 文が長すぎると理解が難しくなります。「次に、果物の名前要素のリストを x 座標に、バーの高さを上座標に指定して、vbar を呼び出します。」長い文は、短い文または箇条書きに分ける必要があります。文章をシンプルにすると、失読症のユーザーや、英語を第一言語として使用しないユーザーにとって特に役立ちます（問題 #10160 を参照）。
  • 「you」と「we」の使用に一貫性がなく、混乱を招き、混乱を招きます: 「ユースケースに応じて使用できる基本的な方法が 2 通りあります」と「別々の呼び出しを使用して、年間の時系列をプロットできます」（同じページの 2 つの例）。一部のページでは、「ユーザーが追加の依存関係をインストールしなければならない場合がある」、「より複雑なレイアウトを作成することができる」など、さまざまな形でリーダーを指定します。
  • 誤字、足りない単語、文法上の誤りがあると、文章が読みづらくなり、情報の信頼性が損なわれ、情報の信頼性が損なわれます。たとえば、「ボケ表現を使うと基本的な棒グラフの作成が簡単に」や、「ユーザーガイドのグリフの説明」などが挙げられます。
  • 構造の不一致は、読み手に不快感を与える可能性があります。たとえば、あるページには十分な注釈が付けられた例があり、別のページの例には説明がない、などです。

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

3. 目標

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

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

Bokeh のドキュメントのほとんどはコントリビューターによって作成されており、新機能やバグ修正の pull リクエストの一部としてドキュメントが含まれています。ドキュメント開発フェーズの一部で既存のドキュメントの編集やリファクタリングを行いますが、将来的にも通用するドキュメントを作成、管理するためのワークフローに重点を置きます。コントリビューターができる限り簡単に、一貫して高い水準のドキュメントを維持できるようにしなければなりません。

次の 2 つのアプローチでこれを確保します。

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

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

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

テキストの利便性の主な要因は、そのスタイルと構造です。明確で一貫したスタイルでドキュメントを記述すると、読者は気を散らすものや無駄な言葉を使うことなく、すばやく情報を得ることができます。わかりやすい透明性の高い構造のドキュメントで、関連情報を素早く簡単に見つけることができます。

この 2 つの分野について、新規ユーザーにとってのユーザビリティに重点を置いて説明します。これには、ユーザーガイドを中心に、ナラティブ ドキュメントの徹底的なレビューが含まれます。また、ドキュメントのランディング ページを見直して、さまざまなターゲット オーディエンスにより明確に対応し、すべてのユーザーが適切なリソースを迅速に見つけられるようにします。

前述したドキュメント作成の改善と同様に、私は今後の改善に向けた基盤を築くことに注力し、Bokeh のドキュメントで継続的に高い水準を維持していきます。

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

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

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

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

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

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

Sphinx コミュニティと ReadTheDocs コミュニティのメンバーは、OpenGraph と構造化データ用の拡張機能の開発（たとえば、問題 #1758 と #5208）に関心を示しており、今後も緊密に協力していきます。

4. 成果物

まとめると、この Google ドキュメントのシーズンには、次の成果物が提供されることが期待されます。

  • ボケ味のコントリビューター向けドキュメント スタイル ガイドライン
  • PR と CI ワークフローを改訂し、自動化されたドキュメント品質管理を含める
  • ユーザーガイドを編集および再構成
  • ドキュメントのランディング ページを改訂しました
  • ドキュメントのウェブページに含まれる OpenGraph メタデータと、機能する Sphinx 拡張機能

また、Google の「ドキュメント シーズン」の様子を個人ウェブサイト/Medium または Bokeh’s Medium ブログで紹介する「ドキュメントログ」を保管します。このドキュメントは、Google のプロジェクト レポートのベースにもなります。可能な限り、GitHub の問題や pull リクエストという形で、すべての作業を透明性をもって実施します。

5. タイムライン

コミュニティの絆を深める前: 私はすでに Bokeh の GitHub リポジトリに関するいくつかのディスカッションに積極的に参加しており、Bokeh の Google 「Google ドキュメント シーズン」のメンターである Bryan Van de Ven 氏と Pavithra Eswaramoorthy 氏と連絡を取り合っています。今後もボケについて積極的に会話を続け、ビジュアライゼーションを構築して公開することで、ボケにさらに習熟していきます。

コミュニティの絆を深めるフェーズ（8 月 17 日～ 9 月 13 日）:

  • コアチームを知り、メンターと交換してプロジェクト計画を洗練する
  • スケジュールを設定し、メンターへの報告とフィードバックを定期的に行うためのコミュニケーション チャネルを用意します。
  • Bokeh の Slack で、Google の「ドキュメント シーズン」やドキュメント開発フェーズの目標について、関心を持っているすべての 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 ワークフローについて話し合う
  • OpenGraph メタデータの既存の概念実証を、デプロイ可能な Sphinx 拡張機能として開発する
  • Bokeh の協力者との Q&A セッションのフィードバックに基づいて、スタイル ガイドラインを見直します

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

  • PR および CI ワークフローにおけるドキュメントの品質管理用ツールのテストを開始する
  • メタデータ用 Sphinx 拡張機能の開発を継続

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

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

11/02 ～ 11/08 第 8 週:

  • Sphinx 拡張機能をデプロイし、改善された説明のドキュメントとドキュメントのランディング ページを公開する

第 9 週、11/09 ～ 11/15:

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

第 10 週、11/16 ～ 11/22:

  • 残りのタスクを完了する

第 11 週、11/23 ～ 11/29:

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

プロジェクト完了フェーズ

第 12 週、11/30 ～ 12/05:

  • プロジェクト レポートを確定して提出する

第 13 週、12/03 ～ 12/10:

  • プロジェクト評価を完成させて提出する

Google の「ドキュメント」シーズンの終了後:

  • 今後も Bokeh の開発に関わり、Bokeh のドキュメントの制作に取り組んでいきたいと考えています。
  • OpenGraph/構造化データ メタデータ用の Sphinx 拡張機能の開発は今後も継続する予定です。
  • ジャーナリズムの経歴と既存のネットワークを活用して、データ ジャーナリズムのツールとしてボケを広めたいと考えています。たとえば、ジャーナリズムの対象者を念頭に置いてボケについて書いたり、ジャーナリズムの場でボケ表現を使うことをカンファレンスで紹介したりします。

6. 自己紹介

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

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

前の仕事で書いたマニュアルや文書は残念ながら非公開です。そこで、現在はオープンソース プロジェクトへの関与を深めることに力を入れています（以下の例を参照）。私は、Google のデベロッパー向けドキュメントのスタイルガイドや Microsoft のスタイルガイドなど、スタイルガイドを基にしたテクニカル ライティングをベースとしてきました。GitHub、Slack、Linux を定期的に使用しています。Sphinx、Mypy、Sphinx autodoc などのツールを使用して、ナラティブ ドキュメント、docstring、タイプヒントを記述してきました。

現在、フリーランスで仕事をしています。私のスケジュールは、ドキュメントの作成フェーズで週に 25 時間ほど Bokeh のドキュメントに取り組むのに必要な柔軟性を備えています。私は太平洋時間のタイムゾーンで勤務していますが、チームのスケジュールとニーズに合わせて喜んで対応しています。

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

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

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