このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- Tor プロジェクト
- テクニカル ライター:
- Swati Thacker
- プロジェクト名:
- Tor のマニュアル ページを書き換える
- プロジェクト期間:
- 長期実行（5 か月）
プロジェクトの説明
TOR メンターと話し合い、このプロジェクトに対する期待を理解したうえで、TOR マニュアル ページ（https://2019.www.torproject.org/docs/tor-manual.html.en）の構造と形式を統一し、ユーザーにとって便利なクイック リファレンスとなるように、以下のアイデアを提案します。このプロジェクトは 3 か月で完了し、以下のアイデアは月ごとに分類されます。
1 か月目:
このページの目次を作成してください。TOC には、概要トピックと、構成オプションの 9 つのカテゴリすべてに関する見出しが含まれます。今月末までに、ユーザーは指先でさまざまな設定カテゴリに移動できるようになります。目次は次のようになります。
- 概要 – TOR がこれらのさまざまなオプション カテゴリの構成を保持する場所、それらがすべて同時に配置されている場合、構成ファイルの名前とデフォルトの場所、コマンド オプションを使用するためのルール、ユーザーがこれらのオプションを変更する方法に関する情報を追加します。（構成ファイルの形式のトピックの導入文から情報を含めることができます）。
- 全般オプション
- クライアント オプション
- サーバー オプション
- ディレクトリ サーバー オプション
- ネットワーク オプションのテスト
- サービス拒否攻撃の軽減オプション
- ディレクトリ コンソール サーバーのオプション
- 非表示のサービス オプション
- 非永続化オプション
2 か月目
マニュアル ページの目的は、各オプションの機能と方法に関する質問に迅速に回答することです。現在、選択肢は構造化された形式で文書化されておらず、各選択肢の情報が段落にまとめられているため、ひと目で情報を見つけにくくなっています。オプションに関する既存の情報はすべて、テンプレートを使用して再編成する必要があります。今月末までに、既存のオプションと今後追加される新しいオプションを、一貫した形式で文書化します。また、この形式により、TOR マニュアルを今後「man」ページとして簡単に使用できるようになります。
- まず、サーバー オプション、クライアント オプションなど、各オプション カテゴリに関する簡単な説明を追加します。説明は、各カテゴリにどのようなオプションが表示されるかをユーザーに知らせるために役立ちます。
- テンプレートを作成して、各オプションを記述するための一貫した形式を定義します。テンプレートに次のセクション/サブセクションを含めることを提案します。
- 名前: 文書化するオプションの名前。例: BandwidthBurst
- 概要: オプションのコマンドライン構文の概要。例: BandwidthBurst N バイト
- 説明: 構成オプションの内容とデフォルト値について説明します。例: このオプションを使用して、トークン バケットの最大サイズ（バストとも呼ばれます）を各方向の指定されたバイト数に制限します。このオプションのデフォルトは 1 Gbyte です。
- オプションの値: オプションで許可される値を一覧表示し、説明します。各値の機能と、ユーザーが値を入力する方法について詳しく説明します。
3 か月目
現在、構成オプションには 9 つのグループ/カテゴリがあります。検索性を高め、クイック リファレンスとして、9 つのカテゴリごとにアルファベット順に並べられた構成オプションをリストするインデックス ページを作成します。これらのカテゴリは、使用頻度に応じて並べ替えることができます。最もよく使用されるオプションのカテゴリが上位に表示されます。
3 か月が経過すると、TOR マニュアルの改訂版を作成できます。このマニュアルは、TOR の設定を変更する際のユーザー向けのクイック リファレンスとして使用できます。