Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.
Resumo do projeto
- Organização de código aberto:
- Projeto Tor
- Redator técnico:
- Swati Thacker
- Nome do projeto:
- Reescrever a página do manual do Tor
- Duração do projeto:
- De longa duração (5 meses)
Project description
Após uma discussão com os mentores dos TOR para entender quais são as expectativas deles em relação ao projeto, proponho as seguintes ideias para estabelecer uma estrutura e um formato consistentes para a página do Manual do TOR (https://2019.www.torproject.org/docs/tor-manual.html.en) e transformá-la em uma referência útil e rápida para os usuários. Este projeto será concluído em três meses, e as ideias a seguir estão divididas por mês.
Mês 1:
Crie um índice para esta página. O TOC inclui um tópico de visão geral e os cabeçalhos de todas as nove categorias de opções de configuração. Até o final deste mês, os usuários poderão navegar para diferentes categorias de configuração na ponta dos dedos. O TOC vai ficar assim:
- Visão geral : adicione informações sobre onde o TOR mantém a configuração para essas diferentes categorias de opções, se elas estiverem todas em um só lugar, o nome e o local padrão do arquivo de configuração, as regras para usar as opções de comando e como os usuários podem modificar essas opções. (Podemos incluir informações do texto introdutório no tópico THE FORMATO DE ARQUIVO DE CONFIGURAÇÃO).
- Opções gerais
- Opções do cliente
- Opções do servidor
- Opções do servidor de diretório
- Como testar opções de rede
- Opções de mitigação de negação de serviço
- Opções do servidor da autoridade do diretório
- Opções de serviço ocultas
- Opções não persistentes
Mês 2:
O objetivo da página manual deve ser responder rapidamente a perguntas sobre o que cada opção faz e como. Atualmente, as opções não estão documentadas em um formato estruturado, e as informações sobre cada opção são apresentadas em parágrafos, o que dificulta a busca rápida de informações. Todas as informações existentes sobre as opções precisam ser reorganizadas usando um modelo. Até o final deste mês, teremos um formato consistente para documentar as opções atuais e as novas opções no futuro. Além disso, esse formato facilita o uso do manual do TOR como páginas “man” no futuro.
- Primeiro, adicione uma breve descrição sobre cada categoria de opção, como as Opções de servidor, de cliente etc. As descrições ajudam os usuários a saber quais opções esperar em cada categoria.
- Crie um modelo para definir um formato consistente para documentar cada opção. Suponho que as seguintes seções/subseções sejam incluídas no modelo.
- Nome: o nome da opção que está sendo documentada. Exemplo: Largura de banda
- Sinopsis: o resumo da sintaxe da linha de comando da opção. Exemplo: WidthBurst N bytes
- Descrição: descreva o que a opção de configuração faz, qual é o valor padrão. Exemplo: use essa opção para limitar o tamanho máximo do bucket de token, também conhecido como busrt, ao número determinado de bytes em cada direção. O padrão dessa opção é 1 Gbyte.
- Valor da opção: liste e descreva os valores permitidos pela opção. Descreva em detalhes o que cada valor faz e como o usuário deve inseri-los.
Mês 3:
Atualmente, existem nove grupos/categorias de opções de configuração. Para facilitar a pesquisa e como referência rápida, crie uma página de índice que liste as opções de configuração em ordem alfabética dentro de cada uma das nove categorias. Essas categorias podem ser ordenadas de acordo com a prioridade de uso, com as opções mais usadas no topo.
Ao final de três meses, é possível produzir um Manual do TOR recondicionado que pode ser usado pelos usuários como uma referência rápida para modificar as definições de configuração no TOR.