このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- Tor プロジェクト
- テクニカル ライター:
- スワティ サッカー
- プロジェクト名:
- Tor のマニュアル ページを書き換える
- プロジェクトの期間:
- 長時間(5 か月)
プロジェクトの説明
TOR のメンターと話し合い、このプロジェクトに求められる内容を理解しました。その後、TOR マニュアル ページ(https://2019.www.torproject.org/docs/tor-manual.html.en)の一貫した構成と形式を確立し、ユーザーにとって有用でクイック リファレンスにするために、以下のアイデアを提案します。このプロジェクトは 3 か月で完了し、次のアイデアが月ごとに示されます。
1 か月目:
このページの目次を作成します。TOC には、概要のトピックと、構成オプションの 9 つのカテゴリすべての見出しが含まれます。今月末までに、ユーザーはさまざまな構成カテゴリに指先で移動できるようになります。TOC は次のようになります。
- 概要 - これらのさまざまなオプション カテゴリの構成を TOR が保持する場所(すべて一度に配置されている場合)、構成ファイルの名前とデフォルトの場所、コマンド オプションを使用するためのルール、ユーザーがこれらのオプションを変更する方法に関する情報を追加します。(構成ファイルのトピックにある導入テキストの情報を含めることができます)。
- 全般オプション
- クライアントのオプション
- サーバー オプション
- ディレクトリ サーバー オプション
- ネットワーク オプションのテスト
- サービス拒否攻撃の緩和策
- Directory Authority Server オプション
- 非表示のサービス オプション
- 非永続的オプション
2 か月目
マニュアルページの目的は、各オプションの機能とその方法に関する質問にすばやく回答できるようにすることです。現在、各オプションは構造化された形式で文書化されておらず、各選択肢の情報は段落で表されているので、情報を一目で見つけるのが困難です。オプションに関する既存の情報はすべて、テンプレートを使用して再編成する必要があります。今月末までに、既存の選択肢と今後の新しい選択肢について、一貫性のあるフォーマットで記録する予定です。さらに、この形式にすると、TOR マニュアルを今後「man」ページとして使用しやすくなります。
- まず、[サーバー オプション]、[クライアント オプション] など、各オプションのカテゴリについて簡単な説明を追加します。この説明は、各カテゴリでどのような選択肢があるかをユーザーが把握するのに役立ちます。
- テンプレートを作成して、各オプションを文書化するための一貫した書式を定義する。以下のセクション/サブセクションをテンプレートに含めることを提案します。
- Name: 文書化されるオプションの名前。例: BandwidthBurst
- 概要: オプションのコマンドライン構文の概要です。例: BandwidthBurst N バイト
- 説明: 構成オプションの機能とデフォルト値を記述します。例: このオプションを使用して、トークン バケットの最大サイズ(バス RT)を各方向の指定されたバイト数に制限できます。このオプションのデフォルト値は 1 GB です。
- オプション値: オプションで使用できる値をリストアップします。それぞれの値の動作と、ユーザーが値を入力する方法について詳しく説明します。
3 か月目
現在、構成オプションには 9 つのグループとカテゴリがあります。検索可能性を高め、クイック リファレンスとして、9 つのカテゴリごとに構成オプションをアルファベット順に並べ替えてリストするインデックス ページを作成します。これらのカテゴリは、使用頻度の高い順に並べることができます。最もよく使用されるオプションのカテゴリが上位に表示されます。
3 か月が経過すると、TOR の構成を変更する際にユーザーが簡単に参照できる、修復された TOR マニュアルを作成できます。