このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- HPX
- テクニカル ライター:
- リストバフ
- プロジェクト名:
- 既存の HPX ドキュメントの編集と合理化
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
私の提案は、既存の HPX ドキュメントの内容を編集し、合理化することです。私の提案は、標準期間（3 か月）のプロジェクトで、STE||AR グループのマニュアルの 2 章「HPX Build System and Launching」（1）と「Configure HPX Applications」（2）の改訂に焦点を当てています。
「HPX Build System and Launching」の章には、文法上の誤りがいくつかあります。また、「CMake」のような用語に混乱を招くことや、大文字アルファベットの使用方法に一貫性がありません。さらに、情報の繰り返しが含まれています。これを必要に応じて再配置、統合、カットする予定です。「HPX アプリケーションの構成」の章には、対処すべき文法上のエラーもいくつかありますが、この章の主な懸念事項は、ユーザー フレンドリーであることです。この章には、設計上の主な課題が 3 つあります。
見出しがテキストの中に埋もれてしまい、章を読みづらくなっている。 現時点では、ユーザーがマニュアルを注意深く読み、各表の目的を理解する必要があります。多くのユーザーが取扱説明書をこのように操作することはできません。特に、以前コンテンツを読んだことがある場合は特にそうです。代わりに、各テーブルに明確で区別できる見出しを設けて、ユーザーがテキストをスクロールした場合でも見やすいようにします。
特定の見出しの下のさまざまなプロパティをリストする場合、それらのプロパティは論理的な順序に従っていません。 宿泊施設は共通のテーマのもとでグループ化されますが、サブグループ化がないため、情報が分散しているように見えます。たとえば、地域性を扱うプロパティ、別のテーマを扱うプロパティ、地域性を扱う別のプロパティに遭遇する場合があります。見出しの下に内部構造がないため、特定のサブトピックに関するすべての情報を見つけることが困難になっています。そこで、見出しごとに類似の情報をより明確にグループ化するために、いくつかのチャートを再構成することを計画しています。
ユーザーは、特定の手順を完全に理解するために、セクション間を行き来しなければならない（または、マニュアルを 2 つのタブで開く）必要があります。 マニュアルでは、前のセクションの「このステップはステップ 11 の後に実行します」のような曖昧な表現が使われているため、章でユーザーを上へスクロールするか、ハイパーリンクをたどって正確な指示を理解させるように、前のセクション内の 1 つの文にユーザーを誘導する箇所があります。この方法では繰り返しはなくなりますが、特定の順序で実行する必要があるタスクであるため、指示の理解が難しくなります。代わりに、ユーザーがセクションやドキュメントを切り替えて読むプロセスを中断せずに済むように、より具体的な表現を含めることをおすすめします。
標準のタイムラインが完了する前にこれらのセクションを完了した場合、STE||AR グループの User Documentation の「Why HPX?」(3) ページもクリーンアップしたいと思います。このページには、重複のある導入コンテンツが含まれていますが、それを統合したいと考えており、大文字表記（特に専門用語）と語調の不一致により、統一感のない印象を与えています。私の目標は、STE||AR グループの取り組みを、より統一された一貫性のある方法で紹介することでした。