Проект Фонда Викимедиа

На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.

Краткое описание проекта

Организация с открытым исходным кодом:
Фонд Викимедиа
Технический писатель:
Павитра Эшварамурти
Название проекта:
Улучшение документации для технических документалистов и видеооператоров Викимедиа.
Длина проекта:
Стандартная продолжительность (3 месяца)

Описание Проекта

1. Обо мне

Я познакомился с программным обеспечением с открытым исходным кодом несколько месяцев назад и почти сразу почувствовал себя ошеломленным его безграничными возможностями. Пытаясь пробиться сквозь миллионы проектов, я узнал об инициативах с открытым исходным кодом, таких как Google Summer of Code и Outreachy. Google Season of Docs показался интересным, а идеи проекта Фонда Викимедиа возбудили мое любопытство, поэтому я начал исследовать дальше.

До сих пор мое путешествие было одновременно захватывающим и запутанным, наполненным вопросами «Подожди, что?», «Ааа, я понял!» и «Должен ли я это прокомментировать?». Сообщество Викимедиа поддерживало нас на каждом этапе. От редактирования страниц до создания расширений — я каждый день узнавал что-то новое.

Как и ожидалось, процесс подачи заявки стал для меня воротами в сообщество открытого исходного кода. Это предложение основано на моем собственном опыте новичка.

2. Проект

2.1. Контур

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

2.2. Практические результаты

  • T197006 [https://phabricator.wikimedia.org/T197006] — улучшить документацию для документалистов Викимедиа:

    • Добавьте советы и примеры в документацию/руководство по стилю. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Добавьте специфическую информацию MediaWiki для определенных жанров в шаблоны и предложения технической документации: руководства пользователя, инструкции, руководства по быстрому запуску, примечания к выпуску и файлы README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Тестируйте и улучшайте рекомендации по приоритезации технической документации. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Разработайте стратегию сбора контента для различных жанров документации.
    • Разработайте стратегию коммуникации и сотрудничества для документации MediaWiki.
    • Создайте контрольный список, по которому авторы смогут проверять свои документы перед публикацией.
    • Расширьте структуру документации для новых технических писателей. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Составьте список задач по технической документации, подходящих для хакатонов. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Создайте центр технических писателей, который будет содержать полезные ресурсы.

  • Улучшите документацию для видеооператоров MediaWiki:

    • Создайте краткое руководство пользователя для создания общего скринкаста.
    • Создавайте шаблоны скринкастов для MediaWiki для пошаговых руководств и руководств.

  • T214522 [https://phabricator.wikimedia.org/T214522] — Создайте скринкаст «Введение в Phabricator».

2.3. Растянуть цель

  • Перепроверьте содержимое и обновите документацию WikiProject Screencast. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Наставники

Zulip будет основным способом общения с моими наставниками. Для обсуждений с сообществом будут использоваться IRC-каналы и электронная почта Викимедиа. Обсуждение конкретных задач будет происходить в разделе комментариев задач Phabricator.

4. Дискуссия

Этот проект в целом разделен на два этапа:

(i) Улучшить существующие ресурсы для технических писателей Викимедиа.

(ii) Создайте полезные шаблоны для потенциальных видеооператоров.

(i) Улучшить существующие ресурсы для технических писателей Викимедиа.

В прошлом было несколько инициатив по улучшению документации MediaWiki с разной степенью успеха. Назвать несколько:

  • https://www.mediawiki.org/wiki/User:Zakgreant/Tech_Docs Plan (2011--01/P6M)
  • https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
  • https://www.mediawiki.org/wiki/Thread:Project:Current_issues/Restructure MediaWiki.org (или:_Document_how_it_was_and_execute_it)
  • https://www.mediawiki.org/wiki/User:Waldir/Docs

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

Ниже приводится фрагмент из двухнедельного отчета стажера Outreachy 2018, Анны и так https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/ :

«Руководство по стилю MediaWiki далеко от совершенства, особенно потому, что оно слишком сильно полагается на внешние ссылки, не выделяя при этом, какие практики оно считает лучшими. К сожалению, эта проблема не ограничивается только MediaWiki, поскольку она проявляется и в другой документации, например, в лучших практиках перевода. Писатели остаются без хороших и надежных ресурсов для выполнения своей работы, что приводит к трудностям с определением целевой аудитории и правильного стиля письма. А пользователи, особенно новые, могут столкнуться с проблемами при понимании новых концепций и процессов».

T197006 [https://phabricator.wikimedia.org/T197006] также проливает свет на некоторые области технической письменной документации, которые нуждаются в улучшении. Очевидно, что Documentation/Style_guide — это то, с чего следует начать.

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

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

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

Даже имея эти документы, новым техническим писателям понадобится дополнительная помощь, и мы должны им ее оказать. Руководство для новых технических писателей доработано, а список задач, подходящих для хакатонов, составлен в зависимости от уровня сложности.

Наконец, тестируется и совершенствуется документ для понимания процесса управления и ведения документации — «Приоритизация технической документации».

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

(ii) Создайте полезные шаблоны для потенциальных видеооператоров.

«Один из самых сложных способов изучить что-либо, связанное с графикой, — это читать простой текст. Представьте также, что произойдет, если в вашем руководстве упоминается неправильная версия программного обеспечения - с помощью только текстовых руководств часто становится невозможным воссоздать серию действий, когда меню и формулировки в приложении меняются, поскольку нам не хватает всех подсказок, которые мы обычно используем. использовать.

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

Мы также можем добавить к скринкасту переведенные субтитры, чтобы их могли просматривать люди, для которых язык не является родным, или заменить звуковую дорожку на другие языки».

В приведенном выше фрагменте из «Справочника по скринкастингу» [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf] Ян Озсвальд объясняет значение скринкастов. Это может быть особенно полезно для учебных пособий по настройке среды разработки MediaWiki, написанию расширений, использованию Gerrit и многому другому.

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

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

Наконец, пересматривается и обновляется главный источник информации для видеооператоров Викимедиа — WikiProject Screencast.

5. Ориентировочный график

Период объединения сообщества (1 августа – 1 сентября)

  • Подробно проанализируйте проект вместе с моими наставниками.

  • Обсудить это:

    • Как часто следует пересматривать задачи.
    • Делитесь расписаниями и выбирайте еженедельный/ежедневный рабочий процесс.
    • Инструменты и ресурсы, которые можно использовать.
    • Двухнедельные и ежедневные отчеты по проекту.

  • Создайте необходимые задачи и подзадачи в Phabricator.

  • Создавайте черновики, чтобы компенсировать личные обязательства на этапе разработки документа.

Неделя 1 (2–8 сентября)

  • Улучшите документацию/Style_guide:

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

  • Улучшите руководство для новых технических писателей:

    • Разверните структуру документации.

Неделя 2 (9–15 сентября)

  • Работа по приоритезации технической документации:

    • Оценить рабочую документацию; найдите примеры хороших описаний задач и расстановки приоритетов.
    • Изучите тенденции и запишите общие трудности.
    • Используйте информацию и примеры для документирования стандартов определения приоритетов.

Неделя 3 (16–22 сентября)

  • Создайте следующую дополнительную документацию для технических писателей:

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

Неделя 4 (23–29 сентября)

  • Добавьте информацию о написании в наиболее распространенных жанрах MediaWiki в шаблоны и предложения технической документации:

    • Документируйте в MediaWiki лучшие практики написания руководств пользователя, кратких руководств, файлов README, примечаний к выпуску и инструкций.

  • Добавьте указания по повышению зрелости технических коммуникаций. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Повышение зрелости --_strategic_directions]

Неделя 5 (30 сентября – 6 октября)

  • Улучшите документацию по привлечению новых сотрудников:

    • Обновить страницу: Задания по технической документации для хакатонов. (Задание: добавляйте на эту страницу подходящие задачи на протяжении всего периода проекта)

  • Создайте центр технических писателей

    • Создайте целевую страницу со ссылками на полезные страницы и ресурсы.
    • Добавьте необходимые ссылки на новые и существующие страницы для облегчения навигации между ними.

Неделя 6 (7–13 октября)

  • Создайте следующие документы по созданию видео для MediaWiki:

    • Краткое руководство пользователя по созданию общего скринкаста с указанием проекта Screencast.
    • Шаблоны для: Пошаговых руководств по использованию программного обеспечения/инструмента; Учебники по разработке новых инструментов.

  • Создайте список идей скринкастов для MediaWiki.

Неделя 7 (14–20 октября)

  • Работа над видеороликом «Введение в Фабрикатор»:

    • Используйте шаблон (созданный на прошлой неделе) для составления сценария.
    • Оцените эффективность шаблона и при необходимости улучшите его.
    • Получите обратную связь и доработайте проект.

Неделя 8 (21–27 октября)

  • Опубликуйте видео «Введение в Phabricator»:

    • Выберите и установите программное обеспечение.
    • Настройте среду и создайте скринкаст.
    • Запишите возникшие проблемы и решения.

Неделя 9 (28 октября – 3 ноября)

  • Работа над улучшением документации проекта Screencast:

    • Изучите структуру и обсудите необходимость внесения изменений.
    • Просмотрите упомянутое программное обеспечение.
    • Изучите и обновите список программного обеспечения.

Неделя 10 (4–10 ноября)

  • Продолжайте совершенствовать документацию проекта Screencast:

    • Оцените и улучшите руководство и сценарии.
    • Просмотрите галерею скринкастов.

Неделя 11 (11–17 ноября)

  • Завершить работу над документацией проекта Screencast:

    • Находите и добавляйте новые видео в галерею.
    • Внесите необходимые структурные изменения.

Неделя 12 (18–24 ноября)

  • Работайте над любыми нерешенными задачами.

  • Напишите итоговый отчет:

    • Ознакомьтесь с двухнедельными/ежедневными отчетами и соберите необходимую информацию.
    • Спланируйте структуру отчета и напишите черновик.
    • Улучшите и доработайте проект на основе отзывов наставника.

Неделя 13 (25–29 ноября)

  • Предоставьте окончательный отчет и оценку наставника.

6. Отслеживание прогресса

Ежедневные обновления прогресса будут сообщаться моим наставникам через Zulip. Сообщество Викимедиа может отслеживать мой прогресс с помощью Phabricator или двухнедельных отчетов по проекту.

7. Другие обязательства

Я учусь на дневном отделении колледжа, и мой академический осенний семестр совпадает с графиком сезона «Документация». Следовательно, в мои обязательства входит сдача экзаменов в колледж.

Первый внутренний экзамен: с 18 по 24 августа.

Второй внутренний экзамен: с 29 сентября по 6 октября.

Экзамен в конце семестра: с 11 по 30 ноября.

Я также планирую посетить свою первую публичную конференцию PyCon India с 12 по 15 октября благодаря удачному расположению в этом году. Я считаю, что это будет прекрасная возможность познакомиться с новыми людьми и провести содержательные беседы.

Для выполнения этих обязательств в ориентировочном графике предусмотрены менее весомые задачи на соответствующие недели. Я намерен сдать не более 20 основных кредитов в осеннем семестре, чтобы иметь достаточно времени для разработки документации. (Обычный студент набирает в среднем 25 кредитов за семестр)