このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- HPX
- テクニカル ライター:
- rstobaugh
- プロジェクト名:
- 既存の HPX ドキュメントの編集と合理化
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
既存の HPX ドキュメントのコンテンツを編集して合理化することを提案します。私の提案は、STE||AR グループのマニュアルの 2 つの章、「"HPX Build System and Launching"」（1）と「"Configure HPX Applications"」（2）の改訂に焦点を当てた標準的な期間（3 か月）のプロジェクトです。
「HPX ビルドシステムと起動」の章には、文法上の誤りがいくつかあります。また、わかりにくい表現や、「CMake」などの用語の大文字と小文字の不一致があります。さらに、重複する情報も含まれています。必要に応じて、これらの情報を並べ替え、統合、削減する予定です。「HPX アプリケーションの構成」の章にも、修正が必要な文法上の誤りがいくつかありますが、この章の主な懸念事項はユーザー フレンドリーさです。この章では、次の 3 つの主要な設計問題に対処する予定です。
一部の見出しがテキスト内に埋もれてしまい、章をひと目で読みにくくなっています。現在、ユーザーはマニュアルを注意深く読んで、各テーブルの目的を理解する必要があります。ほとんどのユーザーは、特にすでに内容を読んでいる場合は、この方法で取扱説明書を操作しません。代わりに、各表に明確で区別しやすい見出しを付け、ユーザーがテキストをスクロールしたときに簡単に見つけられるようにします。
特定の見出しの下にさまざまなプロパティをリストする場合、プロパティは論理的な順序に従っていません。 宿泊施設は共通のテーマでグループ化されていますが、サブグループがないため、情報が分散しているように見えます。たとえば、地域区分を扱う複数のプロパティ、別の主題を扱ういくつかのプロパティ、局所性を扱う別のプロパティに出会う場合があります。見出しの下位に内部構造がないため、特定のサブトピックに関するすべての情報を探すのが難しくなります。そのため、いくつかのグラフを再編成し、類似する情報を各見出しの下にわかりやすくグループ化することを計画しています。
特定の手順を十分に理解するには、セクション間を行き来する（またはマニュアルを 2 つのタブで開かなければならない）必要があります。 マニュアルの前のセクションで「この手順はステップ 11 の後に行う」などあいまいな表現が使用されているため、読者が正確な手順を理解するために上へスクロールするか、ハイパーリンクをたどらなければならない箇所があります。この方法では繰り返しを排除できますが、タスクは特定の順序で実行する必要があるため、指示を理解しにくくなります。代わりに、より具体的な文言を追加して、ユーザーがセクションやドキュメントを切り替えて読書を中断しなくて済むようにすることをおすすめします。
標準のタイムラインが終了する前にこれらのセクションを完了できたら、STE||AR グループのユーザー ドキュメントの「Why HPX?」（3）ページも整理したいと思います。このページには、繰り返しの多い導入コンテンツが含まれています。このコンテンツは統合することをおすすめします。また、大文字（特に専門用語）とトーンの不整合があり、統一感がありません。私の目標は、STE||AR グループの取り組みについて、より統一され、一貫性のある紹介を作成することです。