このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソースの組織:
- Qubes OS
- テクニカル ライター:
- c1e0
- プロジェクト名:
- トラブルシューティング ガイドを統合
- プロジェクトの長さ:
- 標準の期間（3 か月）
プロジェクトの説明
ABSTRACT
トラブルシューティング ガイドは、プロダクトやサービス使用時に発生する問題をエンドユーザーが解決できるように作られています。トラブルシューティング ガイドは、問題が発生したときにユーザーをサポートできるため、重要です。問題が発生したときにユーザーがプロダクトを放棄しないようにします。Qubes は世界中で毎日何千人ものユーザーが使用しています。そのうちの多くのユーザーは、ある時点で問題に直面し、トラブルシューティング ガイドを必要とします。
トラブルシューティング ガイドの現状
現在、QubesOS のトラブルシューティング ガイドは多くのページに分散されており、不完全な場合もあり、ユーザーの問題の診断をサポートする際に同じ手順を何度も投稿することになります。利用可能なガイドには症状と対応策のレイアウトがないため、ユーザーが問題と解決策を照らし合わせることが困難です。また、ソーシャル メディア（Reddit）、Qubes Github の問題ページ、#qubes-users フォーラムで繰り返し言及されている問題がいくつかありますが、現在のトラブルシューティング ガイドには記載されていません。
提示したトラブルシューティング ガイドが、現在のトラブルシューティング ガイドよりも改善されているのはなぜですか？
提案するトラブルシューティング ガイドは、正確かつ簡単にナビゲートできるように、完全かつ構造化されたものです。このガイドでは、問題を解決する方法について、簡潔な手順を説明しています。問題と対処方法のレイアウトで、問題が記載され、その問題を解決するための推奨される解決策が記載されます。トラブルシューティングは検索エンジン向けに最適化され、ユーザーがソーシャル メディアや検索エンジンで検索している問題を考慮して説明されています。これらの変更により、ユーザーが検索エンジンで公式のトラブルシューティング ガイドを見つけ、問題の解決策をすばやく簡単に見つけられるようになります。
提案されているトラブルシューティング ガイドの構成とタイムライン
Qubes OS トラブルシューティング ガイドの提案された構造を作成しました。こちらをご覧ください: https://docs.google.com/document/d/187NlnEvctYVVUnRuGtwY2PkYBVxBSSPfpSwZEaczqL8/edit?usp=sharing。このレイアウトには、トラブルシューティングの各セクションが作成されるおおよその時間枠が伴います。このレイアウトは、メンターからのフィードバックを受けて実装されます。構成とタイムフレームは、メンターのフィードバックに基づいて変更される場合があります。
プロジェクトの目標
- トラブルシューティング ガイドを再構成し、よりわかりやすい、統合された症状と対応策のレイアウトにしました。
- 既存のトラブルシューティングを書き直し、わかりやすい手順を記載します。
- 必要に応じてスクリーンショットを追加する
- Qubes をインストールして試し、発生した問題を記録します。Lenovo Thinkpad、Dell Latitude、Acer Aspire の 3 台のパソコンを使用しています。これらの各パソコンで Qubes を試し、エラーを記録してトラブルシューティングを検証します。
- 既存のガイドに古い情報が含まれている場合は、削除します。
- トラブルシューティングが正確であることを確認します。現時点では、既存のトラブルシューティング ガイドには「This is unofficial, third-party documentation. Qubes OS Project は、このページの正確性を保証するものではありません。ご注意ください」と表示されます。トラブルシューティングの手順が正しいことが確認されると、この警告は破棄されます。トラブルシューティングの正確性を確保するため、（可能であれば）トラブルシューティングを自分の PC でテストするか、オンラインで他のユーザーが解決策を検証したかどうかを確認します。
- 外部向けのトラブルシューティング（フォーラムと GitHub から）を公式のトラブルシューティング ウェブページに移行します。
- Reddit（r/QubesOS）、Stack Exchange、#qubes-users Google グループ、GitHub Issues で、ユーザーが直面しているその他の問題を調査します。また、Keywordtool.io や UberSuggest.com などのキーワード調査ツールを使用して、Google などの検索エンジンで頻繁に検索されている質問を探します。
- トラブルシューティング ガイドでユーザーの問題が解決しない場合のために、[サポートを受ける] セクションを追加します。例については、Fedora のトラブルシューティング ページ（https://docs.fedoraproject.org/ja/fedora/rawhide/install-guide/install/Troubleshooting/#sect-troubleshooting-getting-help）をご覧ください。
このプロジェクトの目的
テクノロジー、特にサイバーセキュリティとプライバシーに情熱を注いでいます。文章作成は私の強みの一つです。セキュリティとプライバシーという私の 2 つの主要な関心が交差しているため、Qubes OS に特に興味があります。私は、DuckDuckGo や Tor など、セキュリティとプライバシーに重点を置いた他のサービスを愛用しています。Qubes OS を最近知りましたが、とても気に入っています。
私がこのプロジェクトの対象者であると考える理由
- セキュリティ、プライバシー、優れたドキュメントの作成に情熱を注いでいます。
- Qubes OS のインストール時や使用時に事象が発生したため、トラブルシューティングの手順をご案内させていただきます。
- この 1 か月間、Qubes オペレーティング システムの技術的な側面について学習しました。また、Qubes OS のドキュメントも幅広く調査しました。ドキュメント編集プロセスを把握するために、プルリクエストを作成しました（https://github.com/QubesOS/qubes-doc/pull/1005/files）。
- 私は最近、Tor プロジェクトでインターンシップを終えました。私の役割はテクニカル サポートと執筆でした。ヘルプデスクで働いていたとき、Tor ブラウザのインストールや使用時に問題が発生したユーザーから、何百件もの質問を受けました。こうしたユーザーの問題のトラブルシューティングをサポートすることで、簡潔でわかりやすいトラブルシューティングの手順を書く方法を学びました。
- Tor Project で働いていたときも、Markdown を使用して技術ドキュメントを作成していました。バージョン管理には Git、GitHub、GitLab を使用しました。