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

ESLint プロジェクト

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

プロジェクトの概要

オープンソース組織:: ESLint
テクニカルライター:: Khawar
プロジェクト名:: 構成ドキュメントの整理/書き換え
プロジェクトの長さ:: 標準期間（3 か月）

プロジェクトの説明

概要

このプロジェクトの目的は、ESLint の構成ドキュメントを再構成し、効果的な情報アーキテクチャを作成することです。これにより、ナビゲーションが容易になり、ドキュメントのユーザビリティと有用性が向上します。

プロジェクトの概要現状の ESLint の設定ドキュメント（https://eslint.org/docs/user-guide/configure）では、多くの情報を 1 ページにまとめています。ページにヘッダー、サブヘッダー、適切な段落があっても、ドキュメントが読みづらい場合があります。ページの特定のセクションに移動する方法がないため、特定のセクションに興味があるユーザーにとって不便です。また、情報が整理されていないため、情報が失われ、目的を果たせず、ユーザーに余分な手間をかけることもあります。

ただし、これらの問題は、一連の慎重な手順で解決できます。この再編成の最初のステップとして、コンテンツの監査を提案します。コンテンツ監査は、情報の表示に関する問題を特定するだけでなく、コンテンツ自体の欠点（古い情報や不完全な情報など）を明らかにするのにも役立ちます。次に、情報アーキテクチャ（IA）を作成してナレッジネットワークを公開する予定です。これにより、さまざまなトピックに応じて情報をクラスタ化し、密接に関連するさまざまなトピック間のリンクを見つけることができます。これらの 2 つの方法で得られた分析情報は、単一ページのドキュメントを複数のページに分割するために使用されます。パッケージ全体をマークダウンでリンクして相互参照できます。その結果、構成ドキュメントの整理が進み、ナビゲーションと理解が容易になります。

目的私はかなり前からオープンソースソフトウェアを使っていますが、Linting ソフトウェアの知識と同様、この用語にはかなり新しく馴染みがありました。edX で Python を学び始めたとき、小さなエラーがコード全体を台無しにしてしまうことに驚きました。コードをテストしてエラーを特定できると便利だと思い、linting という用語を知りました。linting ソフトウェアはまだ使いこなしていませんが、今後は役立つと確信しています。

電気工学のバックグラウンドとプログラミングの経験があるため、コーディングの問題とプログラマの要件をよりよく理解できます。また、技術と専門的なコミュニケーションの修士号を取得しているため、ユーザーの立場に立って、人々の生活をより便利にしようとしています。私のスキルと専門知識は、このプロジェクトにとって良い組み合わせとなり、ESLint のドキュメントに付加価値をもたらします。

目標このプロジェクトの包括的な目標は、ESLint の構成ページにあるドキュメントをわかりやすくし、ユーザーに負担をかけないようにすることです。プロジェクトを成功させるには、コンテンツのナビゲーションを簡単にし、複雑さを排除することが重要です。プロジェクトの重要な目標は次のとおりです。- 包括的なコンテンツ監査を実施する - 情報アーキテクチャを作成して情報の流れを把握する - 情報アーキテクチャを改善してドキュメントを再編成する - コンテンツのさまざまなセクション間のリンクと参照を特定する - 再構成要件を満たすために必要に応じてドキュメントの一部を書き換える/編集する

- コンテンツが柔軟で再利用可能であることを確認する

プロジェクトの説明 ESLint の構成は、ESLint をカスタマイズできる重要な機能です。構成に興味があるユーザーは、一度に 1 ～ 2 つの側面に興味を持っているはずです。そのため、ユーザーが関心のある特定のトピックに案内し、効率的に解決策を提示することが重要です。ESLint の構成ドキュメントの現在の状態には有用な情報が数多く含まれていますが、ユーザーが負担やフラストレーションを感じたり、混乱を招いたりできるように構成されています。たとえば、ESLint でのサードパーティプラグインの使用に興味がある人は、下にスクロールし、パーサー、環境、グローバルの指定に関する説明を読む必要があります。その行為自体はユーザーを疲弊させ、ウェブサイトから離れてしまう原因になります。同様に、ユーザーがページの途中で特定のセクションに移動したり、類似のトピックを確認したりしたい場合、そのような支援が提供されていないため、簡単には行えません。ドキュメントの質は、どれだけ綿密に作成されたとしても、その有用性にかかっているため、この問題には早急な対応が必要です。以降の説明では、これらの問題と関連する問題の解決策を提案します。

コンテンツの監査構成ドキュメントを再編成するプロセスの最初のステップは、包括的なコンテンツ監査を行うことです。監査では、古いコンテンツ、重複コンテンツ、不足しているコンテンツなどの主な問題を特定することを目的としています。その結果作成されたコンテンツ監査用スプレッドシートは、管理チームとドキュメントチームと共有され、フィードバックが求められます。これにより、ドキュメントの構成と提示方法に関する新しい戦略を策定できます。

情報アーキテクチャの作成構成ドキュメント内のナレッジネットワークや情報の流れを理解するには、情報アーキテクチャ（IA）を作成すると役に立ちます。コンテンツ監査の結果は、情報の流れを理解して構築するための優れた基盤となります。その後、IA の改善版が作成され、ドキュメントをより適切に整理して表示できるようになります。この改善された IA は、現在のコンテンツを再構成するだけでなく、ドキュメントのさまざまなセクション間のリンクと分岐を特定し、効率的なネットワークを構築します。たとえば、「ルールの構成」のコンテンツの後に、「インラインコメントによるルールの無効化」につながるリンクを配置できます。このようなリンクを他にも特定して、ドキュメントのさまざまなセクションの間に関係を構築できます。

目次コンテンツ監査と IA では、ドキュメントの特定のセクションやサブセクションにリンクする詳細な目次を作成するための十分な情報が得られます。セクションごとに個別のファイルを作成し、他のセクションに適切な参照を追加すると、ドキュメント全体の価値を高めることができます。構成ドキュメントにアクセスしたユーザー向けに目次を作成すると、ウェブサイト内でのユーザーの移動をサポートできます。目次には、簡潔かつ包括的な内容にするために、1 つ目のレベルと 2 つ目のレベルの見出しをすべて含めることができます。たとえば、Prettier（https://prettier.io/docs/ja/index.html）でドキュメントを整理するために使用される方法がこれに該当します。

すべてのドキュメントは Markdown を使用して作成されるため、シンプルで整理された状態を保つことができます。ドキュメントは今後拡張や変更が行われる可能性があるため、再利用できるように特別な注意を払って作成します。

使用するツールプロジェクトの作業中に役立つ重要なツールは次のとおりです。 - Draw.io: 必要に応じて IA のイラストを作成します。 - Atom（または同様のエディタ）: Markdown でドキュメントを作成、編集します。

- GitHub を使用してドキュメントのバージョン管理を保証

マイルストーン提案書の提出からプロジェクトの完了まで、次の暫定的なマイルストーンにより、プロジェクトが期限までに完了し、プロセスの適切な流れが維持されます。

2020 年 7 月 10 日～ 2020 年 8 月 16 日: 提案書の審査と選定 Eslint のドキュメントを確認し、プロジェクトの完了に必要なスキル（Markdown の記述、GitHub でのコラボレーションなど）を習得します。また、GitHub を通じてドキュメントの作成にも携わり、他のユーザーと連携してドキュメントをより深く理解していきます。

2020 年 8 月 17 日～ 2020 年 9 月 13 日: コミュニティとの交流コミュニティとの交流期間中は、メンターや関係チームとのディスカッションに基づいて提案を精査します。必要に応じて、目標とマイルストーンも編集します。また、プロジェクトの作業に使用するツールを絞り込みます。

2020 年 9 月 14 日～ 2020 年 9 月 19 日: コンテンツ監査プロジェクトの開始として、構成ドキュメントの包括的なコンテンツ監査を行います。目的は、コンテンツとその表示に関する問題をハイライトすることです。

2020 年 9 月 20 日～ 2020 年 9 月 25 日: 情報アーキテクチャ（IA）コンテンツ監査の後、構成ドキュメントの IA を作成します。ここでは、知識ネットワークをわかりやすい方法で提示することに焦点を当てます。これにより、情報の流れを改善できます。

2020 年 9 月 26 日～ 2020 年 9 月 30 日: リンクと参照このフェーズでは IA を分析し、ドキュメントのさまざまなセクション間のリンクと参照をマッピングします。また、すべてのセクションの階層を作成して、プロセス内の IA を改善します。

2020 年 10 月 1 日～ 2020 年 10 月 3 日: 最終マップコンテンツ監査と IA から得られたインサイトの助けを借りて、再編成された構成ドキュメントに実装する最終的なマップを作成します。この包括的なマップには、目次、トピックの階層、ドキュメントのセクション間のリンクと相互参照のリストが含まれます。

2020 年 10 月 4 日～ 2020 年 10 月 5 日: ディスカッションこの時点で、つまりドキュメントを編集する前に、調査結果と計画をメンターと関係チームに提示します。フィードバックは、計画を精査し、必要に応じて変更を加えるのに役立ちます。

2020 年 10 月 6 日～ 2020 年 10 月 20 日: 書き換えと編集この期間に、作業が必要なドキュメントのセクションを編集、更新します。構成ドキュメントの一部のセクションが書き換えられたり、新しい内容が追加されたりする場合があります。このフェーズでは、ドキュメントが正確で、最新の状態であり、柔軟で、再利用可能であることを確認します。

2020 年 10 月 21 日～ 2020 年 10 月 25 日: 修正とリンクこの段階では、文法や構造上の誤りをなくすため、また内容の正確性を再確認するために、作業内容を見直します。また、IA に従ってセクション間にリンクと参照を追加し、ドキュメントが先ほど作成したナレッジマップに基づいていることを確認します。

2020 年 10 月 26 日～ 2020 年 10 月 31 日: 提出用の最終版すべての Markdown ファイルをリンクし、目次を作成し、下書きをメンターに共有します。これは、完全なパッケージ形式の最初の下書きの提出となります。

2020 年 11 月 1 日～ 2020 年 11 月 5 日: 最初のレビューこの 5 日間、最初の下書きについてメンターと話し合います。フィードバックを受け取り、私のアイデアについて話し合い、必要な編集のリストを作成します。

2020 年 11 月 6 日～ 2020 年 11 月 12 日: 最初の編集メンターのフィードバックを参考に、ドキュメントの最初の下書きを編集します。実際の編集はコメントやフィードバックの性質に応じて行われますが、編集フェーズでは再利用、正確性、柔軟性の目標が重視されます。

2020 年 11 月 13 日～ 2020 年 11 月 15 日: 2 回目の審査最初の編集が完了しましたら、進捗状況についてメンターおよび担当チームともう一度話し合います。これらのディスカッションでは、最初のバージョンに加えた編集に焦点を当て、編集プロセスで発生した可能性のあるその他の問題にも注目します。

2020 年 11 月 16 日～ 2020 年 11 月 19 日: 2 回目の編集その後、4 日間かけてドキュメントの編集を行います。完成したバージョンについては、メンターと話し合い、最終的な形を決定します。このフェーズが完了すると、ドキュメントは最終的な形になり、ウェブサイトと GitHub リポジトリにアップロードできるようになります。

2020 年 11 月 20 日～ 2020 年 11 月 23 日: ウェブサイトへのアップロード必要な編集をすべて行った後、書類がウェブサイトにアップロードされます。ドキュメントの作成には数日かかるため、このプロセスで発生した問題は適切に対処されます。

2020 年 11 月 24 日～ 2020 年 11 月 28 日: プロジェクトレポートこの 5 日間に、プロジェクトの詳細なレポートが作成されます。目標、課題、問題、提示された解決策は、プロジェクトレポートの一部となります。レポートはフィードバック対象のメンターと共有されます。

2020 年 11 月 29 日～ 2020 年 11 月 30 日: 最終提出プロジェクト、すべてのファイル、プロジェクトレポートがメンターに提出されます。プロジェクト全体のレビューは、メンターと関係チームとのミーティング/ディスカッションを通じて行われます。

プロジェクト全体を通して、メンターから貴重なフィードバックをもらいます。これらのマイルストーンはすべて、コミュニティボンディングと提案書の審査期間中にメンターとの話し合いに基づいて変更できます。

プロフィールノースカロライナ州立大学で電気工学の学士号と、技術および専門的なコミュニケーションの修士号を取得しています。技術的な文書や編集、コミュニケーションとコンテンツ管理、ウェブ / モバイルユーザビリティ研究、インストラクションデザインの分野で経験があります。オンラインパブリケーション（Global Village Space）のサブエディターや、デューク大学の Duke Forge でコミュニケーションインターンとして働いた経験があります。また、創作活動にも興味があります。