Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.
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 do TOR para entender quais são as expectativas deles em relação a este projeto, sugiro 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 rápida e útil para os usuários. Este projeto será concluído em três meses, e as ideias a seguir são divididas por mês.
Mês 1:
Crie um sumário para esta página. O TOC incluirá um tópico de visão geral e os títulos de todas as nove categorias de opções de configuração. Até o final deste mês, os usuários poderão acessar as diferentes categorias de configuração disponíveis. O TOC vai ficar assim:
- Visão geral: adicione informações sobre onde o TOR mantém a configuração dessas diferentes categorias de opções, se elas estão 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 FORMATO DO ARQUIVO DE CONFIGURAÇÃO).
- Opções gerais
- Opções do cliente
- Opções do servidor
- Opções do servidor de diretório
- Como testar as opções de rede
- Opções de mitigação de negação de serviço
- Opções do servidor da autoridade de diretório
- Opções de serviço ocultas
- Opções não persistentes
Mês 2:
O objetivo da página de manual deve ser responder rapidamente a perguntas sobre o que cada opção faz e como. No momento, as opções não são documentadas em um formato estruturado, e as informações sobre cada opção são apresentadas em parágrafos, o que dificulta a visualização das informações. Todas as informações existentes sobre as opções precisam ser reorganizadas com o uso de um modelo. Até o fim deste mês, vamos ter um formato consistente para documentar as opções atuais e qualquer nova opção 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ções, como opções do servidor, opções do cliente e assim por diante. As descrições ajudam os usuários a saber o que esperar em cada categoria.
- Crie um modelo para definir um formato consistente para documentar cada opção. Proponho que as seções/subseções a seguir sejam incluídas no modelo.
- Nome: o nome da opção que está sendo documentada. Exemplo: BandwidthBurst
- Sinopse: resumo da sintaxe de linha de comando da opção. Exemplo: BandwidthBurst 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 tokens, também conhecido como busrt, ao número de bytes especificado em cada direção. O padrão é 1 gigabyte.
- 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, há nove grupos/categorias de opções de configuração. Para melhorar o potencial de pesquisa e como uma referência rápida, crie uma página de índice que liste opções de configuração em ordem alfabética dentro de cada uma das nove categorias. Essas categorias podem ser ordenadas pela prioridade de uso, com as categorias de opções mais usadas no topo.
No final de três meses, podemos produzir um manual de TOR renovado que pode ser usado como referência rápida pelos usuários para modificar as configurações de configuração no TOR.