Скоро: система отслеживания ошибок для документации WordPress

Документация WordPress будет улучшаться как на дрожжах. На данный момент попытка внести свой вклад в документацию может привести к путанице. Если вы не знаете текущую документацию вдоль и поперек, найти пробелы или отсутствующие части, требующие внимания, непросто. Вот где в игру вступает средство отслеживания проблем.

Что такое средство отслеживания проблем с документацией?

Трекер проблем с документами для документирования — это то же самое, что trac для кода. Средство отслеживания проблем представляет собой центральное место, где пользователи и участники могут сообщать и отслеживать ход решения проблем, связанных с документацией.

В проекте Drupal есть хороший пример , если вы хотите увидеть его в действии.

Идея возникла у команды WordPress Docs Team. Когда Шивон МакКаун изложила идею трекера, она назвала две важные проблемы, которые решит трекер проблем:

• Люди хотят внести свой вклад в документацию, но у них нет центрального списка задач, которые они могут сесть и решить.
• Проводится все больше и больше дней участников, и наш трекер задач станет местом, где организаторы смогут найти задачи на день.

Примеры проблем, о которых можно сообщить, включают устаревшую документацию, неполные документы, страницы, которые необходимо отредактировать, отсутствующие разделы, неработающие ссылки, примеры кода, которые не работают или нуждаются в обновлении.

Тэмми Листер разработала макет трекера, запланированного для WordPress.

Во многих отношениях он проще, чем trac, и предназначен для того, чтобы любой мог легко  создать отчет по проблеме.

Docs Tracker находится в разработке

У меня была возможность пообщаться с Сэмюэлем Сидлером . Он помогает организовать проект трекера под кодовым названием «Документрон».
Чтобы получить представление о системе, которую участники использовали до сих пор, я спросил его, как в настоящее время решаются проблемы с документацией. Кажется, что сейчас нет центрального места, где все могли бы присоединиться и работать вместе. Он ответил:

В настоящее время проблемы с документацией решаются и отслеживаются вручную отдельными участниками. Нет простого способа сообщить о проблемах или запросить новую документацию. Средство отслеживания проблем с документацией позволит сделать две вещи: 1) любой может сообщить о проблеме с документацией и 2) команда документации может отслеживать все открытые проблемы, чтобы получить более полное представление о состоянии документации по всему проекту.

Сидлер считает, что новый трекер проблем поможет значительно расширить возможности внесения вклада в документацию WordPress. «Трекер ориентирован в первую очередь на то, чтобы упростить работу команды документации. Но любой член сообщества сможет сообщить ему о проблемах, открывая двери для участия», — сказал он. Он ожидает, что помимо команды документации, группа поддержки также, вероятно, будет использовать трекер для документации, которой они управляют.

Дизайн был завершен, и Сидлер сообщает, что Отто с радостью согласился разработать новый трекер. Как скоро мы увидим его использование на WordPress.org? Сидлер говорит: «Трудно сказать, сколько времени займет создание системы отслеживания проблем, особенно в связи с предстоящими праздниками, но мы ближе, чем когда-либо». План состоит в том, чтобы сначала развернуть его в бета-версии, а Sidler будет организовывать пользователей для тестирования. «Мы добавим ссылки на несколько документов, чтобы протестировать интерфейс отчетности с конечными пользователями, прежде чем внедрять его во всю документацию».

Трекер проблем с документацией — обязательный инструмент для любого крупного проекта с открытым исходным кодом. Сидлер надеется, что это упростит управление проблемами.

В идеале, будет сообщено о большем количестве проблем, а затем они будут исправлены с помощью системы отслеживания проблем. Наличие простого способа сообщить о проблеме должно увеличить количество сообщений о проблемах. Точно так же наличие центрального места для отслеживания проблем облегчит их исправление.

Я рад видеть, что средство отслеживания проблем с документацией реализовано на WordPress.org. Он может экспоненциально увеличить вклад в документы, а также сотрудничество между членами группы по работе с документами.