Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione di Documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- Tor Project
- Technical Writer:
- Swati Thacker
- Nome progetto:
- Riscrivere la pagina del manuale di Tor
- Durata del progetto:
- A lungo termine (5 mesi)
Project description
Dopo una discussione con i mentor di 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 di 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 verrà completato entro 3 mesi e le seguenti idee sono suddivise per mese.
Mese 1:
Crea un sommario per questa pagina. L'Indice dei contenuti includerà un argomento di panoramica e le intestazioni di tutte le 9 categorie di opzioni di configurazione. Entro la fine del mese, gli utenti potranno accedere facilmente alle diverse categorie di configurazione. L'Indice dei contenuti avrà il seguente aspetto:
- Panoramica: aggiungi informazioni su dove TOR gestisce la configurazione per queste diverse categorie di opzioni, se si trovano tutte in un unico posto, il nome e la posizione predefinita del file di configurazione, le regole per utilizzare le opzioni di comando e come gli utenti possono modificarle. Possiamo includere le informazioni del testo introduttivo nell'argomento FORMATO DEL FILE DI CONFIGURAZIONE).
- Opzioni generali
- Opzioni client
- Opzioni server
- Opzioni del server directory
- Test delle opzioni di rete
- Opzioni di mitigazione dei Denial of Service
- Opzioni del server dell'autorità di directory
- Opzioni di servizio nascoste
- Opzioni non persistenti
Mese 2:
Lo scopo della pagina del manuale deve essere rispondere rapidamente alle domande su cosa fa e come funziona ogni opzione. Al momento, le opzioni non sono documentate in un formato strutturato e le informazioni su ogni opzione sono presentate in paragrafi che rendono difficile trovare le informazioni a colpo d'occhio. Tutte le informazioni esistenti sulle opzioni devono essere riorganizzate utilizzando un modello. Entro la fine del mese avremo un formato coerente per la documentazione delle opzioni esistenti e di eventuali nuove opzioni in futuro. Inoltre, questo formato consentirà di utilizzare facilmente il manuale di TOR come pagine "man" 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 la documentazione di ogni opzione. Propongo di includere le seguenti sezioni/sottosezioni nel modello.
- Nome: il nome dell'opzione di cui viene fornita la documentazione. Esempio: BandwidthBurst
- Sinossi: il riepilogo della sintassi della riga di comando dell'opzione. Esempio: N byte BandwidthBurst
- 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 burst, al numero specificato di byte in ogni direzione. Il valore predefinito di questa opzione è 1 Gbyte.
- Valore dell'opzione: elenca e descrivi i valori consentiti dall'opzione. Descrivi in dettaglio la funzione di ciascun valore e come l'utente deve inserirli.
Mese 3:
Attualmente sono disponibili 9 gruppi/categorie di opzioni di configurazione. Per migliorare la ricerca e come riferimento rapido, crea una pagina di indice che elenchi le opzioni di configurazione ordinate alfabeticamente all'interno di ciascuna delle nove categorie. Queste categorie possono quindi essere ordinate in base alla priorità di utilizzo, con le categorie di opzioni più utilizzate in alto.
Al termine di 3 mesi, siamo in grado di produrre un Manuale TOR ricondizionato che può essere utilizzato come riferimento rapido dagli utenti per modificare le impostazioni di configurazione in TOR.