Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- Projet Tor
- Rédacteur technique:
- Swati Thacker
- Nom du projet:
- Réécrire la page du manuel Tor
- Durée du projet:
- Longue durée (5 mois)
Project description
Après avoir discuté avec les mentors TOR pour comprendre leurs attentes concernant ce projet, je propose les idées suivantes afin d'établir une structure et un format cohérents pour la page du manuel TOR (https://2019.www.torproject.org/docs/tor-manual.html.en) afin de la transformer en une référence rapide et utile pour les utilisateurs. Ce projet sera achevé en trois mois. Les idées suivantes sont réparties par mois.
Mois 1:
Créez une table des matières pour cette page. La table des matières comprendra un sujet de présentation et les titres de toutes les neuf catégories d'options de configuration. D'ici la fin du mois, les utilisateurs pourront accéder aux différentes catégories de configuration en un seul geste. La table des matières se présente comme suit:
- Présentation : ajoutez des informations sur l'emplacement où TOR gère la configuration de ces différentes catégories d'options, si elles se trouvent toutes à la même place, le nom et l'emplacement par défaut du fichier de configuration, les règles d'utilisation des options de commande et la façon dont les utilisateurs peuvent modifier ces options. (Nous pouvons inclure des informations du texte d'introduction sous la section FORMAT DU FICHIER DE CONFIGURATION).
- Options générales
- Options client
- Options du serveur
- Options du serveur d'annuaire
- Tester les options réseau
- Options de mitigation du déni de service
- Options du serveur d'autorité d'annuaire
- Options de service masquées
- Options non persistantes
Mois 2:
L'objectif de la page du manuel doit être de répondre rapidement aux questions sur l'utilité et le fonctionnement de chaque option. Actuellement, les options ne sont pas documentées de manière structurée, et les informations sur chaque option sont présentées dans des paragraphes, ce qui rend difficile la recherche d'informations en un coup d'œil. Toutes les informations existantes sur les options doivent être réorganisées à l'aide d'un modèle. D'ici la fin du mois, nous proposerons un format cohérent pour documenter les options existantes et les nouvelles options à venir. De plus, ce format permettra d'utiliser facilement le manuel TOR comme pages de manuel à l'avenir.
- Tout d'abord, ajoutez une brève description de chaque catégorie d'options, telles que les options du serveur, les options du client, etc. Les descriptions aideront les utilisateurs à savoir quelles options sont disponibles dans chaque catégorie.
- Créez un modèle afin de définir un format cohérent pour documenter chaque option. Je propose d'inclure les sections/sous-sections suivantes dans le modèle.
- Nom: nom de l'option documentée. Exemple: BandwidthBurst
- Synopsis: résumé de la syntaxe de ligne de commande de l'option. Exemple: BandwidthBurst N octets
- Description: décrit la fonction de l'option de configuration et sa valeur par défaut. Exemple: Utilisez cette option pour limiter la taille maximale du bucket de jetons (également appelé busrt) au nombre d'octets donné dans chaque direction. La valeur par défaut de cette option est de 1 Go.
- Valeur de l'option: indiquez et décrivez les valeurs autorisées par l'option. Décrivez en détail la fonction de chaque valeur et la manière dont l'utilisateur doit les saisir.
Mois 3:
Il existe actuellement neuf groupes/catégories d'options de configuration. Pour améliorer la recherche et servir de référence rapide, créez une page d'index qui liste les options de configuration triées par ordre alphabétique dans chacune des neuf catégories. Ces catégories peuvent ensuite être triées en fonction de leur priorité d'utilisation, les catégories d'options les plus utilisées étant en haut.
Au bout de trois mois, nous pourrons produire un manuel TOR remanié qui pourra servir de référence rapide aux utilisateurs pour modifier les paramètres de configuration dans TOR.