このページには、Google シーズンの Google ドキュメントで承認されたテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- ESLint
- テクニカル ライター:
- ハワール
- プロジェクト名:
- 構成のドキュメントの再編成/書き換え
- プロジェクトの期間:
- 標準の長さ（3 か月）
プロジェクトの説明
概略
このプロジェクトの目的は、ESLint の設定ドキュメントを再構成し、効果的な情報アーキテクチャを作成することです。これにより、ナビゲーションが容易になり、ドキュメントのユーザビリティと有用性も向上します。
プロジェクトの概要 現在の状態では、ESLint の設定に関するドキュメント（https://eslint.org/docs/user-guide/configure）に、1 つのページにさまざまな情報が記載されています。ページ上に見出し、小見出し、適切な段落があるにもかかわらず、ドキュメントが圧倒されてしまう場合があります。ページの特定のセクションに移動できないため、そのセクションに興味を持っているユーザーをストレスなく感じることができる。このように整理されていないと、情報が失われ、目的を果たせなくなり、ユーザーにさらなる労力を求めます。
ただし、これらの問題は慎重に行うことで解決できます。この再編成の第一歩として、コンテンツの監査を提案します。コンテンツ監査は、情報を提示する際の問題を特定するのに役立つだけでなく、コンテンツ自体の欠点（古い情報や不完全な情報など）を明らかにするためにも役立ちます。その後、ナレッジ ネットワークを発表する情報アーキテクチャ（IA）を構築します。これにより、さまざまなトピックに基づいて情報をクラスタ化し、さまざまなトピック間のリンクを見つけることができます。この 2 つの手法から得られたインサイトを使用して、単一ページのドキュメントを複数のページに分割します。その後、パッケージ全体をリンクして、Markdown で相互参照できます。その結果、構成ドキュメントがさらに整理され、操作しやすく理解しやすいものになります。
動機 オープンソース ソフトウェアはかなり以前から使用していますが、Linting ソフトウェアの知識と同様に、この用語はかなり新しいものです。edX で Python を学び始めたとき、小さなエラーでコード全体が台無しになるのではないかと考えていました。コードをテストしてエラーを特定できたらいいと思いました。「lint チェック」という用語を知ったのです。私はまだ lint ソフトウェアをあまり使用していませんが、今後私たちの生活はずっと楽になるでしょう。
電気工学のバックグラウンドとプログラミングの経験があれば、コーディングの問題やプログラマーの要件をよりよく理解できます。さらに、技術およびプロフェッショナル コミュニケーションの大学院の学位を持っていることで、私は人々の生活を快適にしようと努めており、ユーザーの代弁者となっています。私のスキルと専門知識は、このプロジェクトにとって良い組み合わせとなり、ESLint のドキュメントに付加価値をもたらすでしょう。
目的 このプロジェクトの包括的な目標は、ESLint の構成ページのドキュメントが理解しやすく、ユーザーを圧倒しないようにすることです。プロジェクトの成功のためには、コンテンツ内を簡単に移動できるようにして、あらゆる複雑さを回避することが重要です。 プロジェクトの重要な目標は次のとおりです。- 包括的なコンテンツ監査の実施 - 情報アーキテクチャを作成して情報の流れを理解する - 情報アーキテクチャを改善してドキュメントを再編成する - コンテンツの異なるセクション間のリンクや参照を特定する - 再構成要件を満たすために必要なドキュメントの部分を書き換え/編集する
- 柔軟性が高く再利用しやすいコンテンツを制作する
プロジェクトの説明 ESLint の構成は、ESLint をカスタマイズするための重要な機能です。構成に関心を持つユーザーは、当然ながら、ある時点で 1 つか 2 つの側面に関心を持ちます。したがって、ユーザーが関心のある特定のトピックに誘導され、効率的にソリューションを提供することが重要です。現在の ESLint の設定ドキュメントには有用な情報が数多く含まれていますが、ユーザーが圧倒され、フラストレーションを感じ、道に迷うような形で整理されています。たとえば、ESLint におけるサードパーティ プラグインの使用について知りたい場合は、パーサー、環境、グローバルの指定に関する説明を下にスクロールする必要があります。この作業全体がユーザーを疲弊させ、ウェブサイトから遠ざかってしまうことになります。同様に、ユーザーがページの真ん中にいて、特定のセクションに移動したい、または類似トピックを閲覧したいだけの場合も、そのようなサポートは提供されていないため、簡単な作業とはいえません。ドキュメントの品質は、どれだけうまく作成されていても、その有用性に依存するため、これらの問題には早急な対応が必要です。以降のディスカッションで、これらの問題とその他の関連する問題の解決策を提案します。
コンテンツの監査 設定ドキュメントを再編成するプロセスの最初のステップは、包括的なコンテンツ監査を実施することです。この監査は、古いコンテンツ、重複、コンテンツの欠落など、いくつかの重要な問題を特定することを目的としています。その結果として作成されたコンテンツ監査スプレッドシートは、フィードバックのために経営陣およびドキュメント チームに共有されます。これは、ドキュメントの構成とプレゼンテーションのための新しい戦略を考案するうえで役立ちます。
情報アーキテクチャの作成 構成ドキュメント内のナレッジ ネットワークや情報のフローを理解するには、情報アーキテクチャ（IA）の作成が役立ちます。コンテンツ監査の結果は、情報の流れを理解し、発展させるための優れた基盤となります。その後、ドキュメントをより適切に整理して提示するために改良版 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）のサブエディター、デューク大学でデューク・フォージのコミュニケーション・インターンを務めていました。それと同時に、創作文に興味があります。