Tor-Projekt

Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:

Tor Project

Technischer Redakteur:

Swati Thacker

Projektname:

Tor-Handbuch neu schreiben

Projektdauer:

Lang andauernd (5 Monate)

Projektbeschreibung

Nach einer Unterhaltung mit den TOR-Mentoren, um ihre Erwartungen an dieses Projekt zu erfahren, schlage ich die folgenden Ideen vor, um eine einheitliche Struktur und ein einheitliches Format für die TOR-Anleitungsseite (https://2019.www.torproject.org/docs/tor-manual.html.en) zu schaffen, damit sie eine nützliche, schnelle Referenz für Nutzer wird. Dieses Projekt wird in drei Monaten abgeschlossen. Die folgenden Ideen sind nach Monaten aufgeschlüsselt.

Monat 1:

Erstellen Sie ein Inhaltsverzeichnis für diese Seite. Der Inhaltsverzeichnis enthält ein Übersichtsthema und die Überschriften aller neun Kategorien von Konfigurationsoptionen. Bis Ende dieses Monats können Nutzer die verschiedenen Konfigurationskategorien mit nur wenigen Klicks aufrufen. Die Inhaltsübersicht sieht dann so aus:

• Übersicht: Fügen Sie Informationen hinzu, wo TOR die Konfiguration für diese verschiedenen Optionenkategorien verwaltet, ob sie sich alle an einem Ort befinden, den Namen und den Standardspeicherort der Konfigurationsdatei, die Regeln für die Verwendung der Befehlsoptionen und wie Nutzer diese Optionen ändern können. (Wir können Informationen aus dem einleitenden Text unter dem Thema DATEIFORMAT DER Konfigurationsdatei einfügen.)
• Allgemeine Optionen
• Clientoptionen
• Serveroptionen
• Verzeichnisserveroptionen
• Netzwerkoptionen testen
• Optionen zur Abschwächung von Denial-of-Service-Angriffen
• Optionen für Verzeichnisautoritätsserver
• Verborgene Dienstoptionen
• Nicht persistente Optionen

Hinweis: Derzeit werden im TOR-Handbuch auch eine Reihe von Befehlszeilenoptionen aufgeführt. Aus Gründen der Einheitlichkeit und um den Schwerpunkt dieses Handbuchs auf Konfigurationsoptionen zu legen, sollten die Befehlszeilenoptionen meiner Meinung nach von dieser Seite entfernt und als Referenz verlinkt werden.

Monat 2:

Der Zweck der Seite mit der Anleitung muss darin bestehen, schnell Fragen dazu zu beantworten, was die einzelnen Optionen tun und wie. Derzeit sind die Optionen nicht in einem strukturierten Format dokumentiert und die Informationen zu den einzelnen Optionen werden in Absätzen präsentiert, was es schwierig macht, Informationen auf einen Blick zu finden. Alle vorhandenen Informationen zu Optionen müssen mithilfe einer Vorlage neu organisiert werden. Bis Ende dieses Monats werden wir ein einheitliches Format für die Dokumentation bestehender Optionen und aller neuen Optionen in Zukunft haben. Außerdem kann das Handbuch in diesem Format in Zukunft problemlos als Manpage verwendet werden.

• Fügen Sie zuerst eine kurze Beschreibung für jede Optionskategorie hinzu, z. B. „Serveroptionen“ oder „Clientoptionen“. Anhand der Beschreibungen können Nutzer besser nachvollziehen, welche Optionen in den einzelnen Kategorien verfügbar sind.
• Erstellen Sie eine Vorlage, um ein einheitliches Format für die Dokumentation der einzelnen Optionen zu definieren. Ich schlage vor, die folgenden Abschnitte/Unterabschnitte in die Vorlage aufzunehmen.
• Name: Der Name der Option, die dokumentiert wird. Beispiel: BandwidthBurst
• Synopsis: Zusammenfassung der Befehlszeilensyntax der Option. Beispiel: BandwidthBurst N Byte
• Beschreibung: Beschreiben Sie, wozu die Konfigurationsoption dient und was der Standardwert ist. Beispiel: Mit dieser Option können Sie die maximale Token-Bucket-Größe, auch als Burst bezeichnet, auf die angegebene Anzahl von Bytes in jede Richtung begrenzen. Die Standardeinstellung für diese Option ist 1 Gbyte.
• Optionswert: Geben Sie die zulässigen Werte für die Option an und beschreiben Sie sie. Beschreiben Sie ausführlich, wozu die einzelnen Werte dienen und wie Nutzer sie eingeben sollten.

Monat 3:

Derzeit gibt es neun Gruppen/Kategorien von Konfigurationsoptionen. Erstellen Sie zur Verbesserung der Suchbarkeit und als Schnellübersicht eine Indexseite mit Konfigurationsoptionen, die in jeder der neun Kategorien alphabetisch sortiert sind. Diese Kategorien können dann nach der Priorität ihrer Nutzung sortiert werden, wobei die am häufigsten verwendeten Kategorien von Optionen an oberster Stelle stehen.

Nach drei Monaten können wir ein überarbeitetes TOR-Handbuch erstellen, das Nutzern als Kurzanleitung zum Ändern der Konfigurationseinstellungen in TOR dient.