このページは Cloud Translation API によって翻訳されました。

電子プロジェクト

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

プロジェクトの概要

オープンソースの組織:: Electron
テクニカルライター:: Mister Gold
プロジェクト名:: Electron のチュートリアルのフロー
プロジェクトの長さ:: 標準の期間（3 か月）

プロジェクトの説明

プロジェクトの概要

Electron は、JavaScript、HTML、CSS を使用してクロスプラットフォームのデスクトップアプリを構築するための最も一般的なツールの一つです。Electron で構築されたアプリのコレクションには、ほぼ 900 件のエントリがあり、このリストは継続的に増えています。Visual Studio Code、Atom、Postman、Slack、GitKraken などのよく使われているデベロッパーツールのいくつかは、Electron 上に構築されています。

Electron が人気を集めている理由は、学習のハードルが低く、誰でも JavaScript、HTML、CSS スタックを知っている限り、独自のアプリケーションを構築できる点にあります。全体的な急速な成長率を踏まえ、理解しやすく使いやすいチュートリアルとスタートガイドを作成する必要があります。

このプロジェクトの目標は、Electron フレームワークを初めて使用するアプリビルダーに自信を与え、独自の Electron アプリをゼロから開発する際に一貫性のある効率的なエクスペリエンスを提供することを目指しています。

プロジェクトに関する問題

Electron チュートリアルのドキュメントに関連する最も重要な問題は次のとおりです。 1. アプリケーション開発手順の開始点が不明確で、直感的でない導入情報が記載されています。アプリケーション開発プロセスに関連する散在した冗長な情報「スタートガイド」の手順が整理されていないため、信頼できる唯一の情報源がない

プロジェクトの提案書

プロジェクトの目標と上記の問題に基づき、提案される機能強化は次のとおりです。 1. 既存のガイドを更新します。最初のステップをスムーズかつ一貫したものにするには、次のドキュメントを更新して、簡単なものから複雑なものへと段階的に移行する必要があります。 - デベロッパー環境 - 最初の Electron アプリを作成する - アプリに機能を追加する（概要ページを作成する） - アプリのパッケージ化と配布 2. ドキュメントディレクトリを再構成します。新しいデベロッパーに、開始に不可欠なステップと、追加ステップと見なすことができるステップを示すために、最初のアプリケーションをできるだけ速く稼働させるためのステップを、視覚的にわかりやすく分割して、コンテキストに沿って分割する必要があります。再編には、可能な次のステップに関するガイダンスも含まれます。3. アプリケーション開発のドキュメントを整理して統合します。すべての機能について、インストール/有効化方法、クイックスタート方法、初回起動後のアプリの操作方法、配布方法に関する統一された手順を用意する必要があります。4. ドキュメントに electron-api-demos リポジトリを含めます。Electron-api-demos リポジトリには、Electron アプリケーションに機能を追加する方法を示す一連の例が含まれています。この情報は、信頼できる唯一の情報源のコンテンツ戦略と整合するように、アプリに機能を追加するガイドに含める必要があります。5. 電子フィドルの例をドキュメントに統合します。このステップにより、新しいデベロッパーは、手動で手順を繰り返さなくても、特定のコードがどのように機能するかを簡単に確認できます。統合には、更新されたチュートリアルのコードサンプルの作成と、コードブロックに [Fiddle で起動] ボタンを追加することが含まれます。

タイムライン

申請審査期間 - コミュニティと協力するメンバーに慣れ親しみます。コミュニティへの貢献に関するガイドとベストプラクティスをご確認ください。最初の拠出を行います。コミュニティの結びつき - コミュニティを探索します。Electron ドキュメントの現在の状態を確認します。弱点を特定します。1 週目 - プロジェクトのマイルストーンと成果物についてメンターと調整します。2 週目 - 「デベロッパー環境」と「最初の Electron アプリを作成する」のページを修正します。3 週目 - 「アプリケーションアーキテクチャ」、「アプリに機能を追加する」、「アプリのパッケージ化と配布」のページを修正します。アプリに追加できる機能のリストを含む概要ページを作成する 4 週目 - ドキュメントディレクトリを再編成する 5 週目 - electron-api-demos をメインのドキュメントに統合する方法のテンプレートを作成する 6 ～ 7 週目 - electron-api-demos リポジトリを移行する 8 週目 - Electron Fiddle をメインのドキュメントに統合する方法のテンプレートを作成する。最初のサンプルを記述します。週 9 ～ 10 - Electron Fiddle をメインのドキュメントに統合する週 11 - electron-api-demos リポジトリと Electron Fiddle サンプルを移行した後のメインのドキュメントの構造とページを確定週 12 - 結果の評価

マイルストーンの詳細

応募審査期間前半は、コミュニティチャンネルとソースコードのチェックと、プロジェクトに専任の担当者への連絡に的を絞ります。

残りの期間は、貢献文化全般の確認、貢献ガイドとベストプラクティスの確認に充てられます。この時点で、初めての投稿でフローの仕組みを確認できます。

コミュニティの結びつき

今回は、ドキュメントフォルダとそのロードマップを詳しく見ていきます。その情報に基づいて、改善できる弱点（部品の不足や欠落など）を特定できます。可能な場合は pull リクエストを作成してギャップを埋めます。

第 1 週～第 2 週

最初の 1 週間は、予定されているマイルストーンとそのタイムリーな提供について、メンターと調整することに専念します。

2 週目は、デベロッパー環境と最初の Electron アプリの作成に関するページの改訂を行います。開発環境ページの場合、一般的な概要の書き換えと校正が含まれています。「最初の Electron アプリを作成する」ページでは、開始点と終了点を明確にして、一貫した手順ガイドにします。また、冗長な情報（「Electron 開発の概要」と「このサンプルを試す」セクションにある 2 つの類似したコードブロックなど）を削除します。

成果物: Electron アプリケーションのクイックスタート方法に関する、わかりやすい入門ガイドを改訂しました。

3 週目

今週は、1. アプリケーションアーキテクチャページの改善に専念します。具体的には、次のような変更を加えました。 - 「メインプロセスとレンダラプロセス」セクションの既存の情報を書き直し、初めて読む人にとってシンプルで直感的なものにしました。 - アーキテクチャ、プロセスの接続方法、プロセス間の通信方法、主な違いを視覚的に表現しました。画像の例: 1、2、3（品質が低い）。2. Electron アプリに追加できるすべての機能に関する情報を統合。ガイドの書き換えもその一環です。ガイドには、機能のインストール方法や有効化方法に関する一連の統一された手順と、機能の動作例が記載されます。また、利用可能な機能をすべて一覧表示する新しいページ（概要）も作成されます。総合的な手順は次のようになります。 - 概要 - 例: - コードサンプル - 視覚的な例（可能な場合）

アプリケーションの配信ページの簡素化。具体的には、次の変更を行います。 a. アプリケーションパッケージングをアプリケーションディストリビューションガイドに統合。 b. 配信方法を自動と手動に分割。 c. 自動配信の例として electron-forge を取り上げます。 d. アプリケーションパッケージングページから asar に関する情報を取得し、手動配信の例としてソースファイルのコピーと asar アーカイブの作成について説明します。#### 週 4 今週は、ドキュメントディレクトリの再編成に専念します。次の内容が含まれます。

1 - 既存のガイドを少なくとも 3 つのカテゴリに分類します。 a. クイックスタート b. 基本を学ぶ c. 高度な手順

クイックスタートカテゴリには、新規ユーザーがゼロからクイックスタートできるように、一貫した一連のガイドを作成するための基本的なチュートリアル（インストール、構成、ディストリビューション）が含まれます。各ガイドには、シリーズの前のガイドと次のガイドへのリンクを含める必要があります。

構造は次のようになります。 1. 前提条件 2. Electron をインストールします。 3. 基本的なアプリケーションを作成する 4. アプリケーションをパッケージ化/配布する

クイックスタートセクションを完了すると、ユーザーは Electron アプリケーションの仕組みの基本を理解し、完全に機能する配布可能な Electron アプリケーションを使用できるようになります。

「基本を学ぶ」カテゴリには、Electron に関する知識を深め、クイックスタートセクションで作成したアプリケーションを拡張するためのガイドが含まれます。これらのガイドには、次のようなものがあります。 - アプリケーションアーキテクチャ - アプリに機能を追加する - ボイラープレートと CLI

[高度な手順] カテゴリには、Electron アプリケーションの構成と微調整を目的とした高度なガイドが含まれています。 - テストとデバッグ - ユーザー補助 - セキュリティ - アップデート

2 - ドキュメントのページ数を減らす。現行バージョンのドキュメントには、ある程度重複したコンテンツや未分類の指示が含まれています。たとえば、次のドキュメントは、GitHub に移動し、メインのドキュメントから除外することをおすすめします。以下のドキュメントは Electron 開発ガイドラインに固有のものであり、まずソースリポジトリで確認してください。 - Electron の開発 - Chromium の開発 - V8 の開発 - Electron の問題 - Electron のパッチ - プルリクエスト - ソースコードディレクトリ構造 - テスト - コーディングスタイル

削減の主な目的は、膨大な数のガイドをなくし、散らばっているパズルのピースを 1 つにまとめ、初心者の方により構造化され、操作しやすくユーザーフレンドリーなバージョンの Electron ドキュメントを提供することです。

第 5 ～ 7 週

5 週目は、electron-api-demos をメインのドキュメントに統合するテンプレートの準備（方法）に専念します。このテンプレートは次のようになります。 1. メインのドキュメントの [アプリに機能を追加する] で、electron-api-demos 2 に表示されるカテゴリを作成します。各カテゴリを調べて、デモ例をメインのドキュメントに移行します。 - コードサンプルは、ソースコードから取得することも、アプリ内の対応する機能の説明から取得することもできます。 - 移行した各サンプルの後に、関連する説明を追加します。 - 各子サンプル（「システムダイアログを使用する」の子の「エラーダイアログ」など）は、親の下に移行する必要があります。

注 1: electron-api-demos とメインのドキュメントの両方にサンプルがあります（キーボードショートカット、ドラッグ＆ドロップなど）。この場合、electron-api-demos の例が優先され、メインのドキュメントの例は無視されます。

注 #2: Electricron-api-demos アプリケーションの多くのサンプルには、説明した機能や機能のライブデモプレビューが含まれています。この機能は、第 9 週から第 10 週の Electron Fiddle 統合まで無視されます。

新しい例の階層を考慮し、使用可能なすべての機能（第 3 週に作成）を一覧表示したページを更新します。

6 週目と 7 週目は、上記のテンプレートに基づいて、electron-api-demos の例をメインのドキュメントに移行することに専念します。最後のステップとして、electron-api-demos リポジトリを削除するか非推奨にする必要があります。

第 8 ～ 10 週

8 週目は、Electron Fiddle をメインのドキュメントに統合するテンプレートの準備に専念します。このイニシアチブは、Electron の担当者とコミュニティのボランティアによってすでに開始されています（詳細は Issue #20442 を参照）。ただし、適切に完了する必要があります。

Fiddle サンプルを続行する場合の基本的なテンプレートは次のようになります。メインのドキュメント（クイックスタートなど）から例を選択します。この時点で、ドキュメントには electron-api-demos の例も含まれている必要があります。Electron Fiddle で例を再現します（サンプルコードまたはソースコードを開始点として使用します）。フィドルをローカルのフォルダに保存します。 4. サンプルを /docs/fiddles/[カテゴリ]/[セクション]/[デモ] に移動します。* 完了した例の一覧については、問題の「デモのリスト」セクションをご覧ください。5. 問題 #2848 の最初のコメントで説明されているように、[Fiddle で起動] ボタンを追加します。

9 週目と 10 週目は、上記のテンプレートに従って、electron-api-demos の例（すでに Fiddle に変換されている）をメインのドキュメントに統合することに専念します。

第 11 週

今週は、electron-api-demos リポジトリと Electron Fiddle のサンプルの移行が完了した後、執筆プロジェクトの最終化に専念します。これには、次の点が含まれます。 - 既存のすべてのコードサンプルに [Fiddle で起動] ボタンがあることを確認します。 - 既存のすべてのコードサンプルが Fiddle として正しく動作することを確認します。 - メインのドキュメントで electron-api-demos リポジトリが参照されていないことを確認します。

第 12 週

完了した作業の確定。承認チェック。