На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Открытый коллектив
- Технический писатель:
- Анна и так
- Название проекта:
- Улучшить общую справочную документацию.
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание проекта
Первые впечатления Часто встречаются страницы документации, содержащие инструкции без вспомогательных носителей (видео, GIF-файлы, изображения), в то время как другие разделы той же главы содержат более полные записи - например, Edit Collective состоит только из инструкций, а Add Fiscal Host включает в себя поддержка СМИ.
На страницах, которые я просматривал, никакие медиафайлы не описываются с использованием атрибута альтернативного текста. Отсутствие описаний изображений затрудняет полное понимание документации для тех, кто использует программы чтения с экрана, а также для людей с медленным подключением к Интернету, где любой носитель может не загружаться.
Некоторые разделы документации объединяют часто задаваемые вопросы и прямые инструкции по навигации по пользовательскому интерфейсу, например «Изменить финансовый хост» . Поскольку в интерфейсе документации нет оглавления, пользователь, осознающий последствия изменения регистрационных записей и желающий просто объективных инструкций, может воспринять документацию как многословную и слишком косвенную.
Хотя язык технической документации достаточно последователен, в общедоступном Руководстве по стилю слишком мало информации о том, как следует писать документацию. Поскольку на странице «Содействие» упоминается вклад в техническую документацию, как Open Collective, так и потенциальные участники получат пользу от более подробных рекомендаций.
Предложение Я предлагаю пересмотреть страницы помощи пользователям, переосмыслив их представление и текущую структуру.
Методология и сроки Я хочу улучшить документацию Open Collective, работая вместе с сообществом, продвигая циклы непрерывной обратной связи различной продолжительности.
Период объединения сообщества (1 августа – 1 сентября 2019 г.): Знакомство с сообществом Open Collective! Интервьюирование активных участников известных и начинающих проектов, вопросы о текущем состоянии документации (Отчет №1). Принятие к сведению всех внутренних систем, используемых для отслеживания запросов и проблем, а также процесса их документирования в открытых коллективных документах (отчет № 2). Оценка скрытых проблем в текущей версии документации и подготовка плана их решения (Отчет №3).
2–6 сентября: Первый цикл отзывов и корректировок с учетом всех комментариев и предложений, сделанных сообществом в течение периода сплочения сообщества. Наш план хорош для реализации? Есть ли в этом что-то, что нужно изменить? (Отчет №4)
9–20 сентября: Разработка доказательства концепции с менее заполненной главой документации. Проект общедоступного руководства по стилю (Отчет №5).
23-25 сентября: Представление доказательства концепции на оценку (закрытая группа).
26–27 сентября: Нужны ли какие-либо корректировки нашей проверки концепции перед запуском в эксплуатацию? Нам нужно больше времени? Отрегулируйте соответствующим образом. (Отчет №6)
30 сентября – 9 октября: начинается проверка концепции. Второй цикл обратной связи (публичная группа).
10–15 октября: Окончательная проверка концепции, цикл оценки и корректировки. (Отчет №7)
16-20 октября: Небольшой перерыв в деятельности [1].
21 октября – 23 ноября: окончательное руководство по стилю для общественности (отчет №8). Применение всех инструкций, представленных в Руководстве по стилю, на всех страницах пользовательской документации (Отчет №9). Отчет с оценкой всех выполненных мероприятий и дальнейшими рекомендациями для сообщества (Отчет №10).
Срок реализации проекта может быть продлен по запросу.
[1]: Поездка запланирована до подачи заявления на участие в Season of Docs.
Результаты - Десять общедоступных отчетов о выполненной деятельности - Общедоступное руководство по стилю, которое могут использовать как Open Collective, так и сторонние участники - Обновленные страницы пользовательской документации.