Esta página contém os detalhes de um projeto de redação técnica aceito para a temporada de documentos do Google.
Resumo do projeto
- Organização de código aberto:
- Tor Project (link em inglês)
- Redator técnico:
- Swati Thacker (em inglês)
- 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 do 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) para 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 serão divididas por mês.
Mês 1:
Crie um índice para esta página. O TOC vai incluir um tópico de visão geral e os títulos de todas as 9 categorias de opções de configuração. Até o fim deste mês, os usuários vão poder acessar as diferentes categorias de configuração na ponta dos dedos. O TOC será semelhante a este:
- 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 no mesmo 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 FORMATO DE ARQUIVO DE CONFIGURAÇÃO).
- Opções gerais
- Opções do cliente
- Opções do servidor
- Opções do servidor do diretório
- Como testar opções de rede
- Opções de mitigação de negação de serviço
- Opções do Directory Authority Server
- Opções de serviço ocultas
- Opções não persistentes
Mês 2:
A finalidade da página manual precisa ser responder rapidamente perguntas sobre o que cada opção faz e como. No momento, as opções não estão documentadas em formato estruturado, e as informações sobre cada opção são apresentadas em parágrafos que dificultam 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 existentes e as novas opções no futuro. Além disso, esse formato facilitará o uso do manual de 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, Opções do cliente e assim por diante. 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. Proponho 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 Burst
- Sinopse: 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 e qual é o valor padrão. Exemplo: use essa opção para limitar o tamanho máximo do bucket de token, também conhecido como barrar, 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 inserir os valores.
Mês 3:
Atualmente, existem nove grupos/categorias de opções de configuração. Para melhorar a capacidade de pesquisa e servir como referência rápida, crie uma página de índice que liste as opções de configuração classificadas em ordem alfabética dentro de cada uma das nove categorias. Essas categorias podem, então, ser ordenadas de acordo com a prioridade de uso, sendo as categorias de opções mais utilizadas primeiro.
Ao final de 3 meses, podemos produzir um manual de TOR recondicionado que pode ser usado como uma referência rápida pelos usuários para modificar as definições de configuração no TOR.