Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- Proyecto Tor
- Redactor técnico:
- Swati Thacker
- Nombre del proyecto:
- Reescribir la página del manual de Tor
- Duración del proyecto:
- Larga duración (5 meses)
Project description
Después de una conversación con los mentores de TOR para comprender cuáles son sus expectativas con respecto a este proyecto, propongo las siguientes ideas para 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) y convertirla en una referencia útil y rápida para los usuarios. Este proyecto se completará en 3 meses y las siguientes ideas se desglosan por mes.
Mes 1:
Crea un índice para esta página. El DDC 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 con solo deslizar el dedo. El glosario se verá de la siguiente manera:
- Descripción general: Agrega información sobre dónde mantiene TOR la configuración de estas diferentes categorías de opciones, si están todas en un solo lugar, el nombre y la ubicación predeterminada del archivo de configuración, las reglas para usar las opciones de comando y cómo los usuarios pueden modificar estas opciones. (Podemos incluir información del texto introductorio en el tema EL FORMATO DEL ARCHIVO DE CONFIGURACIÓN).
- Opciones generales
- Opciones del cliente
- Opciones del servidor
- Opciones del servidor del directorio
- Opciones de red de prueba
- Opciones de mitigación de denegación del servicio
- Opciones del servidor de la autoridad del directorio
- Opciones de servicio ocultas
- Opciones no persistentes
Mes 2:
El propósito de la página manual debe ser responder con rapidez 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 opción se presenta en párrafos que dificultan la búsqueda de información de un vistazo. Toda la información existente sobre las opciones debe reorganizarse con 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á que el manual de TOR se use como páginas “man” en el futuro.
- En primer lugar, agrega una breve descripción sobre cada categoría de opción, como las opciones del servidor, las opciones del cliente, etcétera. Las descripciones ayudarán a los usuarios a saber qué opciones 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 sub secciones en la plantilla.
- Nombre: Es el nombre de la opción que se documenta. Ejemplo: BandwidthBurst
- 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 qué 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 burst, a la cantidad determinada de bytes en cada dirección. El valor predeterminado de esta opción es 1 GB.
- 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 ingresarlos 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. Luego, estas categorías se pueden ordenar según la prioridad de su uso, y las categorías de opciones más utilizadas se encuentran en la parte superior.
A los 3 meses siguientes, podemos producir un manual de TOR reacondicionado que los usuarios pueden usar como referencia rápida para modificar los parámetros de configuración en TOR.