Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- Progetto Tor
- Technical writer:
- Spettatore swati
- Nome progetto:
- Riscrivi la pagina del manuale di Tor
- Durata del progetto:
- Lunga esecuzione (5 mesi)
Project description
Dopo una discussione con i mentori del TOR per capire quali sono le loro aspettative in merito a questo progetto, propongo le seguenti idee per stabilire una struttura e un formato coerenti per la pagina del manuale TOR (https://2019.www.torproject.org/docs/tor-manual.html.en) al fine di trasformarla in un riferimento rapido e utile per gli utenti. Questo progetto sarà completato in 3 mesi e le idee seguenti sono suddivise per mese.
Mese 1:
Crea un sommario per questa pagina. Il sommario includerà un argomento di panoramica e i titoli di tutte e nove le categorie di opzioni di configurazione. Entro la fine di questo mese, gli utenti potranno passare alle diverse categorie di configurazione a portata di mano. Il sommario sarà simile al seguente:
- Panoramica: aggiungi informazioni su dove TOR mantiene la configurazione per queste diverse categorie di opzioni, se sono tutte in un unico posto, il nome e la posizione predefinita del file di configurazione, le regole per l'utilizzo delle opzioni del comando e il modo in cui gli utenti possono modificarle. (Possiamo includere informazioni tratte dal testo introduttivo nell'argomento FORMATO FILE DI CONFIGURAZIONE).
- Opzioni generali
- Opzioni client
- Opzioni server
- Opzioni server directory
- Test delle opzioni di rete
- Opzioni di mitigazione degli attacchi DoS
- Opzioni server autorità di directory
- Opzioni di servizio nascosto
- Opzioni non persistenti
Mese 2:
Lo scopo della pagina del manuale deve essere quello di rispondere rapidamente alle domande su cosa fa ciascuna opzione e come. Al momento, le opzioni non sono documentate in un formato strutturato e le informazioni su ciascuna opzione sono presentate in paragrafi, rendendo difficile trovare le informazioni a colpo d'occhio. Tutte le informazioni esistenti sulle opzioni devono essere riorganizzate utilizzando un modello. Entro la fine di questo mese, avremo un formato coerente per documentare le opzioni esistenti e qualsiasi nuova opzione in futuro. Inoltre, questo formato consentirà di utilizzare facilmente il manuale TOR come pagine "uomo" in futuro.
- Innanzitutto, aggiungi una breve descrizione di ogni categoria di opzioni, ad esempio Opzioni server, Opzioni client e così via. Le descrizioni aiuteranno gli utenti a sapere quali opzioni aspettarsi in ogni categoria.
- Crea un modello per definire un formato coerente per documentare ogni opzione. Suggerisco di includere nel modello le seguenti sezioni/sottosezioni.
- Nome: il nome dell'opzione documentata. Esempio: BandwidthBurst
- Riassunto: il riepilogo della sintassi della riga di comando dell'opzione. Esempio: BandwidthBurst N byte
- Descrizione: descrivi la funzione dell'opzione di configurazione e il valore predefinito. Esempio: utilizza questa opzione per limitare la dimensione massima del bucket di token, nota anche come busrt, al numero specificato di byte in ciascuna direzione. Il valore predefinito di questa opzione è 1 Gbyte.
- Valore opzione: elenca e descrivi i valori consentiti dall'opzione. Descrivi nel dettaglio la funzione di ciascun valore e in che modo l'utente deve inserirli.
Mese 3:
Attualmente sono disponibili 9 gruppi/categorie di opzioni di configurazione. Per migliorare la ricercabilità e come riferimento rapido, crea una pagina di indice che elenchi le opzioni di configurazione in ordine alfabetico in ciascuna delle 9 categorie. Queste categorie possono quindi essere ordinate in base alla priorità di utilizzo, posizionando le opzioni più comunemente utilizzate in cima.
Al termine di 3 mesi, siamo in grado di produrre un manuale di Tor del cliente ricondizionato che può essere utilizzato come riferimento rapido dagli utenti per modificare le impostazioni di configurazione nella TOR.