Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- Tor Project
- Rédacteur technique:
- Swati Thacker
- Nom du projet:
- Réécrire la page du manuel Tor
- Durée du projet:
- Exécution longue (5 mois)
Project description
Après avoir discuté avec les mentors de TOR pour comprendre leurs attentes vis-à-vis de ce projet, je propose les idées suivantes pour é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 d'en faire une référence utile et rapide pour les utilisateurs. Ce projet se terminera en 3 mois et les idées suivantes seront décomposées par mois.
Mois 1:
Créez une table des matières pour cette page. La table des matières comprend un thème de présentation et les en-têtes des neuf catégories d'options de configuration. D'ici la fin du mois, les utilisateurs pourront facilement accéder aux différentes catégories de configuration. La table des matières se présentera comme suit:
- Présentation : ajout d'informations sur l'emplacement où TOR gère la configuration de ces différentes catégories d'options, si elles se trouvent toutes en même temps, le nom et l'emplacement par défaut du fichier de configuration, les règles permettant d'utiliser les options de la commande, et la manière dont les utilisateurs peuvent modifier ces options. Nous pouvons inclure des informations tirées du texte d'introduction dans la rubrique DE CONFIGURATION DU FORMAT DU FICHIER.
- Options générales
- Options client
- Options du serveur
- Options du serveur d'annuaire
- Test des options réseau
- Options d'atténuation du déni de service
- Options de serveur Directory Authority
- 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 ce que fait chaque option et comment. Actuellement, les options ne sont pas documentées dans un format structuré, et les informations sur chaque option sont présentées sous forme de paragraphes qui rendent difficile la recherche d'informations d'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 disposerons d'un format cohérent pour documenter les options existantes et toute nouvelle option à l'avenir. De plus, ce format permettra d'utiliser facilement le manuel TOR comme pages "man" à l'avenir.
- Tout d'abord, ajoutez une brève description de chaque catégorie d'option, par exemple les options du serveur, les options client, etc. Elles permettront aux utilisateurs de savoir à quoi s'attendre dans chaque catégorie.
- Créez un modèle pour 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 en cours de documentation. Exemple: bande passante burst
- Description: résumé de la syntaxe de ligne de commande de l'option. Exemple: N octets BandwidthBurst
- Description: décrivez la fonction de l'option de configuration et la valeur par défaut. Exemple: utilisez cette option pour limiter la taille maximale du seau de jetons (busrt) au nombre donné d'octets dans chaque direction. Cette option est définie par défaut sur 1 Go.
- Valeur de l'option: liste et décrit les valeurs autorisées par l'option. Décrivez en détail chaque valeur et comment l'utilisateur doit les saisir.
Mois 3:
Il existe actuellement neuf groupes/catégories d'options de configuration. Pour faciliter la recherche et vous servir de référence rapide, créez une page d'index qui répertorie les options de configuration, classées par ordre alphabétique dans chacune des neuf catégories. Ces catégories peuvent ensuite être classées par ordre de priorité d'utilisation, les catégories d'options les plus couramment utilisées étant les plus courantes.
À l'issue de ces trois mois, nous pourrons produire un manuel TOR reconditionné que les utilisateurs pourront utiliser comme référence rapide pour modifier les paramètres de configuration dans TOR.