На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Проект Тор
- Технический писатель:
- Свати Такер
- Название проекта:
- Переписать страницу руководства Tor.
- Длина проекта:
- Длительный ход (5 месяцев)
Описание Проекта
После обсуждения с наставниками TOR, чтобы понять, каковы их ожидания от этого проекта, я предлагаю следующие идеи для создания последовательной структуры и формата страницы руководства TOR ( https://2019.www.torproject.org/docs/tor ). -manual.html.en ), чтобы превратить его в полезный и быстрый справочник для пользователей. Этот проект будет завершен через 3 месяца, а следующие идеи разбиты по месяцам.
Месяц 1:
Создайте оглавление для этой страницы. Оглавление будет включать обзорную тему и заголовки всех 9 категорий параметров конфигурации. К концу этого месяца пользователи смогут перемещаться по различным категориям конфигурации на кончиках пальцев. ТОС будет выглядеть так:
- Обзор — добавьте информацию о том, где TOR хранит конфигурацию для этих различных категорий параметров, если они все находятся одновременно, имя и местоположение файла конфигурации по умолчанию, правила использования параметров команды и то, как пользователи могут изменять эти параметры. (Мы можем включить информацию из вводного текста в тему ФОРМАТ ФАЙЛА КОНФИГУРАЦИИ).
- Общие настройки
- Опции клиента
- Параметры сервера
- Параметры сервера каталогов
- Тестирование параметров сети
- Варианты смягчения последствий отказа в обслуживании
- Параметры сервера управления каталогом
- Скрытые возможности обслуживания
- Непостоянные варианты
Месяц 2:
Целью страницы руководства должно быть быстрое получение ответов на вопросы о том, что и как делает каждая опция. В настоящее время параметры не документированы в структурированном формате, и информация о каждом параметре представлена в параграфах, что затрудняет быстрый поиск информации. Всю имеющуюся информацию об опциях необходимо реорганизовать с помощью шаблона. К концу этого месяца у нас будет единый формат для документирования существующих вариантов и любых новых вариантов в будущем. Кроме того, этот формат облегчит использование руководства TOR в качестве «справочных» страниц в будущем.
- Во-первых, добавьте краткое описание каждой категории параметров, например «Параметры сервера», «Параметры клиента» и т. д. Описания помогут пользователям узнать, какие варианты ожидать в каждой категории.
- Создайте шаблон, чтобы определить единый формат для документирования каждого варианта. Предлагаю включить в шаблон следующие разделы/подразделы.
- Имя: имя опции, которая документируется. Пример: BandwidthBurst
- Краткое описание: Краткое описание того, как выглядит синтаксис командной строки этого параметра. Пример: BandwidthBurst N байт.
- Описание: Опишите, что делает параметр конфигурации, какое значение по умолчанию. Пример. Используйте эту опцию, чтобы ограничить максимальный размер сегмента токенов, также известный как busrt, заданным количеством байтов в каждом направлении. По умолчанию этот параметр равен 1 Гбайт.
- Значение параметра. Перечислите и опишите значения, которые допускает этот параметр. Подробно опишите, что делает каждое значение и как пользователь должен вводить эти значения.
Месяц 3:
В настоящее время существует 9 групп/категорий параметров конфигурации. Чтобы улучшить возможности поиска и в качестве быстрого справочника, создайте индексную страницу, на которой будут перечислены параметры конфигурации, отсортированные в алфавитном порядке в каждой из 9 категорий. Эти категории можно затем упорядочить по приоритету их использования, причем наиболее часто используемые категории опций располагаются вверху.
По истечении трех месяцев мы можем выпустить обновленное Руководство TOR, которое пользователи смогут использовать в качестве краткого справочника для изменения настроек конфигурации в TOR.