Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- Tor Project
- Escritor técnico:
- Swati Thacker
- Nombre del proyecto:
- Reescribe la página del manual de Tor
- Duración del proyecto:
- Larga duración (5 meses)
Project description
Luego de analizarlos con los mentores de TOR para comprender cuáles son sus expectativas con respecto a este proyecto, propongo las siguientes ideas a fin de establecer una estructura y un formato coherentes para la página del manual de TOR (https://2019.www.torproject.org/docs/tor-manual.html.en) a fin de convertirla en una referencia útil y rápida para los usuarios. Este proyecto se completará en 3 meses y las siguientes ideas se desglosarán por mes.
Mes 1:
Crea un índice para esta página. El TOC incluirá un tema de descripción general y los encabezados de las 9 categorías de opciones de configuración. A fines de este mes, los usuarios podrán navegar a las diferentes categorías de configuración en sus dedos. El TOC se verá de la siguiente manera:
- Descripción general: Agrega información sobre dónde TOR mantiene la configuración de estas diferentes categorías de opciones, si se encuentran todas al mismo tiempo, el nombre y la ubicación predeterminada del archivo de configuración, las reglas para usar las opciones de comando y cómo pueden los usuarios modificar estas opciones. (Podemos incluir información del texto introductorio en el tema CONFIGURATION FILE FORMAT).
- Opciones generales
- Opciones del cliente
- Opciones del servidor
- Opciones del servidor del directorio
- Cómo probar las opciones de red
- Opciones para mitigar el rechazo del servicio
- Opciones del servidor de la autoridad de directorio
- Opciones de servicio ocultas
- Opciones no persistentes
Mes 2:
El propósito de la página manual debe ser responder rápidamente preguntas sobre qué hace cada opción y cómo. Actualmente, las opciones no están documentadas en un formato estructurado, y la información sobre cada una se presenta en párrafos, lo que dificulta la búsqueda de información de un vistazo. Se debe reorganizar toda la información existente sobre las opciones mediante una plantilla. A fines de este mes, tendremos un formato coherente para documentar las opciones existentes y cualquier opción nueva en el futuro. Además, este formato facilitará el uso del manual de TOR como páginas "man" en el futuro.
- Primero, agrega una breve descripción sobre cada categoría de opción, como Opciones del servidor, Opciones del cliente, etc. Las descripciones ayudarán a los usuarios a saber qué opciones pueden esperar en cada categoría.
- Crea una plantilla para definir un formato coherente para documentar cada opción. Propongo que se incluyan las siguientes secciones o subsecciones en la plantilla.
- Nombre: Es el nombre de la opción que se documenta. Ejemplo: widthBurst
- Sinopsis: Es el resumen de cómo se ve la sintaxis de la línea de comandos de la opción. Ejemplo: BandwidthBurst N bytes
- Descripción: Describe lo que hace la opción de configuración y cuál es el valor predeterminado. Ejemplo: Usa esta opción para limitar el tamaño máximo del bucket de tokens, también conocido como busrt, a la cantidad específica de bytes en cada dirección. El valor predeterminado de esta opción es 1 Gbyte.
- Valor de la opción: Enumera y describe los valores que permite la opción. Describe en detalle qué hace cada valor y cómo debe ingresar los valores el usuario.
Mes 3:
Actualmente, hay 9 grupos o categorías de opciones de configuración. Para mejorar la capacidad de búsqueda y como referencia rápida, crea una página de índice que enumere las opciones de configuración ordenadas alfabéticamente dentro de cada una de las 9 categorías. Estas categorías pueden, entonces, ordenarse según la prioridad de su uso, donde las categorías de opciones más usadas se encuentran primero.
Al cabo de 3 meses, podremos elaborar un manual de TOR reacondicionado que los usuarios podrán usar como referencia rápida para modificar los parámetros de configuración en TOR.