Проект Колибри

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

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

Организация с открытым исходным кодом:

Колибри

Технический писатель:

СтефДикс

Название проекта:

Соглашения о стиле документации и рабочих процессах экосистемы Kolibri

Длина проекта:

Длительный ход (5 месяцев)

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

Абстрактный

В этом документе подробно описана реализация рекомендаций по стилю и управлению рабочими процессами для документированной информации Learning Equality для проекта Kolibri Ecosystem.

Обзор

Мое предложение состоит из четырех этапов. На первом этапе я дополню Руководство по стилю документации LE, включив в него рекомендации по доступности, написанию и формату в соответствии с концепциями LE и рекомендациями по стилю при разработке программного обеспечения. На втором этапе я проведу аудит качества документов ReadTheDocs и GoogleDocs. План аудита включает использование контрольных списков для оценки соответствия рекомендациям по стилю. Эти контрольные списки помогут зафиксировать результаты и внести изменения в документацию. На третьем этапе я буду работать над структурой, внешним видом и поведением шаблонов из документов ReadTheDocs и GoogleDocs. Я создам хранилище шаблонов и изображений на Google Диске, определяя каждую категорию шаблонов основных типов документов для повторного использования в будущих реализациях. Я дополню эту задачу созданием шаблонов для отправки проблем с документами, чтобы их можно было легко выявить при проверке запросов на включение. Наконец, я создам Руководство для участников, в котором будут сгруппированы полезные ресурсы для каждой группы сотрудников, чтобы улучшить их опыт доступа к информации.

Цель и сфера применения

Целью этого плана реализации является улучшение опыта использования документов Kolibri конечными пользователями и помощь членам команды и участникам в создании более качественной документации и активном сотрудничестве в сообществе. Эта реализация применяется к ReadTheDocs и подмножествам документов Google Docs в экосистеме Kolibri.

Аудитория

Основная аудитория разработчиков, администраторов и конечных пользователей, которые являются наиболее важными потребителями документации Kolibri. Вторичная аудитория членов команды и соавторов для создания и использования документации Колибри.

Цели

Руководство по стилю и система рабочих процессов для экосистемы Kolibri Documentation ожидает от пользователей: Создавать удобочитаемую документацию на доступном языке и в единообразном формате. Сохраняйте соблюдение методов обеспечения качества в документации. Обеспечьте удобство доступа к информации между каналами документации. Укрепить совместные инициативы в сообществе открытого исходного кода Kolibri.

Источники информации

Моими источниками информации были Kolibri, Kolibri Studio, документы Kolibri Development RTD и наборы инструментов Kolibri с Google Drive.
Замечательная Радина Матич оказала большую помощь в проведении разминочных мероприятий и мероприятий, посвященных конкретному проекту. Ее вклад в то, что организация концептуализирует как «Руководства» и «Руководства», а также относительно существования Руководства для участников, помог мне систематизировать мои идеи и набросать выводы.

Программное обеспечение

Я разработаю черновой вариант Руководства по стилю в Google Docs. Эта платформа документов идеально подходит для повторения, пока она готова к публикации. Для аудита качества я буду использовать Google Forms для проведения и оценки документов. В электронной таблице будут храниться ответы на формы для управления документами. Я проведу рефакторинг документов RTD, используя GitHub. Я работал с Git, Gitkraken, GitHub и Gitlab. У меня есть практические знания Markdown и немного RestructuredText. Я планирую внести свой вклад в исправления документации, чтобы продолжить изучение синтаксиса. Я буду использовать Sharex для изображений и гифок. Мне нравится этот инструмент, потому что он визуализирует в разных форматах вывода. Я буду использовать Diagrams для создания диаграмм и редактирования изображений. Программное обеспечение Diagrams прекрасно интегрируется с GoogleDocs, Google Drive и LibreOffice. Состояние документации На этапе разведки я пересмотрел большую часть документации Колибри. Я обнаружил грамматические ошибки, опечатки, несоответствия в макете, типографике, использовании изображений, а также запутанные пути к документации в большей части документации проекта. Например, в Руководстве пользователя Kolibri раздел устранения неполадок является подтемой, а не темой. Эта информация оказывается достаточно важной, чтобы конечные пользователи могли получить к ней доступ из оглавления. В качестве второго варианта они могут использовать панель поиска и дерево содержания, чтобы расширить другие темы и найти статьи по устранению неполадок.

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

Результаты

Я провел проверку качества Руководства по переводу LE в дополнение к предложениям и комментариям с предварительной формой, которую я объясняю более подробно в задаче аудита качества. Вот некоторые заключительные комментарии, полученные в результате оценки: Неработающие ссылки на веб-сайте ICU Syntax .js. Формат, использованный для создания этих рекомендаций, неверен. Документ представляет собой Руководство, а не Рекомендации. Непоследовательная типографика. Неправильное использование заголовков и названий. Неправильное использование языка и неправильное использование сокращений. Неправильное использование Альтернативных текстов. Чрезмерно повторяющиеся заявления/инструкции.

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

Задачи по конкретному проекту

• Рекомендации Руководства по стилю пользовательской документации LE (комментарии)
• Рекомендации по переводу LE в новых стилях и формате.
• Краткое содержание темы
• График реализации проекта
• Задачи документирования