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

ESLint プロジェクト

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

プロジェクトの概要

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

プロジェクトの説明

抽象化

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

プロジェクトの概要現在の状態での ESLint の設定に関するドキュメント（https://eslint.org/docs/user-guide/setting）には、1 つのページで多くの情報が記載されています。ページ上に見出し、小見出し、適切な段落があるにもかかわらず、ドキュメントが圧倒されるほどです。そのページ内の特定のセクションに移動できないので、そのセクションに興味を持っているユーザーにとって不便になります。情報の整理がおこなわれなくなると、情報が失われ、本来の目的を果たせなくなって、ユーザーに追加の労力を求めるよう求めることにもなりかねません。

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

動機私はオープンソースソフトウェアをかなり以前から使用していますが、lint ソフトウェアに関する私の知識と同様に、私にとって非常に新しい用語です。edX で Python の学習を始めたときは、小さなエラーでコード全体が台無しになってしまうのではないかと考えました。なんらかの形でコードをテストし、エラーを特定できたらいいと思いました。そして「lint チェック」という用語を知ったのです。私はまだ lint ソフトウェアを適切に使用していませんが、この技術があれば今後の生活がずっと楽になるはずです。

電気工学の経歴とプログラミングの経験があれば、コーディングの問題とプログラマーの要件をよりよく理解できます。また、技術と専門的なコミュニケーションの学士号を取得していることで、人々の生活を快適にすることを目指して、ユーザーの擁護者になることもできました。私のスキルと専門知識は、このプロジェクトを効果的に組み合わせて ESLint のドキュメントに付加価値を与えてくれます。

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

- コンテンツの柔軟性と再利用性を高める

プロジェクトの説明 ESLint の設定は、ESLint をカスタマイズするための重要な機能です。構成に関心を持つユーザーは、確実に、ある時点で 1 つか 2 つの側面に興味を持つでしょう。そのため、ユーザーが関心のある特定のトピックに導かれ、効率的にソリューションを提供することが重要になります。現在の ESLint の設定ドキュメントには、有益な情報が多数含まれていますが、ユーザーが圧倒、フラストレーションを感じ、迷子になったと感じられるように構成されています。たとえば、ESLint でのサードパーティプラグインの使用に興味があるユーザーは、パーサー、環境、グローバルの指定に関する議論を通して、下にスクロールする必要があります。この作業全体がユーザーの負担となり、ウェブサイトから離れてしまう可能性があります。同様に、ページの真ん中にいるユーザーが特定のセクションに移動したい場合や、類似トピックを確認したいだけの場合も、そのようなサポートは提供されていないため、容易ではありません。ドキュメントの品質は、どれだけ素晴らしく作成されたとしても、その有用性に依存するため、このような問題は直ちに対処する必要があります。以降のディスカッションで、これらの問題とそれに関連するその他の解決策を提案します。

コンテンツ監査設定ドキュメントを再編成するプロセスの最初のステップは、包括的なコンテンツ監査を実施することです。監査は、古いコンテンツ、重複、コンテンツの欠落など、いくつかの主要な問題を特定することを目的としています。その結果として作成されたコンテンツ監査スプレッドシートは、マネジメントチームやドキュメントチームと共有され、フィードバックが得られます。これは、ドキュメントを構造化して提示するための新しい戦略を策定するうえで役立ちます。

情報アーキテクチャの作成構成ドキュメントに記載されたナレッジネットワークや情報のフローを理解するには、情報アーキテクチャ（IA）の作成が有益です。コンテンツ監査の結果は、情報のフローを理解し、発展させるための優れた基盤となります。その後、ドキュメントをより適切に整理して提示するために、改善されたバージョンの IA が作成されます。この改善された IA では、現在のコンテンツが再構築されるだけでなく、ドキュメントのさまざまなセクション間のリンクやフォークも特定されるため、効率的なネットワークが構築されます。たとえば、「ルールの設定」に続いて「インラインコメントによるルールの無効化」へのリンクが表示されます。このようなリンクが他にもあるため、ドキュメントのさまざまなセクションに関係性を作り出すことができます。

目次セクションごとに別々のファイルを作成し、他のセクションへの適切な参照を追加することで、ドキュメント全体の価値を高めることができます。構成ドキュメントにアクセスするユーザーに対して目次を作成すると、ウェブサイトでの操作が簡単になります。目次には、第 1 レベルの見出しと第 2 レベルの見出しをすべて含めることで、簡潔で包括的なものにすることができます。たとえば、Prettier（https://prettier.io/docs/en/index.html）はドキュメントを整理するために使用しています。

すべてのドキュメントは Markdown を使用して作成されます。これにより、物事をシンプルかつ適切に整理できます。今後、ドキュメントが拡大、変更される可能性があるため、再利用できるように特別な配慮がなされます。

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

- 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 日: 提出用最終版マークダウンファイルをすべてリンクし、目次を作成して、下書きをメンターと共有します。これにより、最初の下書きが完全なパッケージとして提出されます。

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）のサブ編集者、デューク大学でコミュニケーションインターンとして勤務。同時に創作文を書くことにも興味があります。