На этой странице представлена информация о проекте по написанию технических текстов, принятом для участия в конкурсе Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Фонд Linux
- Технический писатель:
- бор
- Название проекта:
- Переработайте размещение и генерацию документации, а также реструктурируйте страницы "Начало работы" и руководства для разработчиков.
- Длительность проекта:
- Стандартная продолжительность (3 месяца)
Описание проекта
Абстрактный :
Документация предназначена для оказания помощи конечным пользователям и разработчикам в использовании продукта или услуги. Хорошая документация очень важна, поскольку она предоставляет пользователям возможность узнать, как использовать программное обеспечение, его функции, советы, рекомендации, а также решить распространенные проблемы, возникающие при использовании программного обеспечения. Она также снижает затраты на поддержку и является частью корпоративной и открытой идентичности продукта: хорошая документация — это признак здоровья продукта и команды разработчиков.
Без качественной документации пользователь может не знать, как эффективно и результативно выполнять вышеперечисленные действия. Документация может сыграть решающую роль в обеспечении успеха продукта, поскольку эффективная коммуникация всегда была и будет основой любого бизнеса или продукта, а качественная документация просто берет эту коммуникацию и помещает ее в удобную структуру, доступную каждому для достижения успеха.
Для любого сайта с документацией необходим хорошо продуманный процесс создания и размещения. В такой организации, как AGL, где существует множество версий и большое количество подробной документации, файлы документации (в формате Markdown) разбросаны по нескольким репозиториям, что делает задачу их поддержки и обновления невероятно сложной и трудоемкой.
Текущее состояние:
- Веб-сайт документации AGL основан на наборе файлов Markdown, полученных из различных репозиториев.
- В настоящее время страницы документации размещены в отдельных исходных кодах в формате Markdown с использованием механизма проекта Cordova.
- В результате получается структура из четырех репозиториев для процесса создания и размещения документации:
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : Содержит шаблон веб-сайта Jekyll.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools]: Содержит инструменты для автоматической генерации технического веб-сайта из файлов Markdown.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : Исходный код (файлы Markdown [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) для общих документов и руководств.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages]: Развернутый репозиторий GitHub Pages для сайта документации [https://gist.github.com/growupboron/docs.automotivelinux.org].
- Инструмент (скрипт), доступный в docs-tools [https://github.com/automotive-grade-linux/docs-tools], отвечает за сбор и создание шаблонов для всех файлов Markdown в соответствии с файлом fetched_files.yml, расположенным в docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Текущий рабочий процесс генерации веб-сайта документации AGL: current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- Файл section_version.yml содержит ссылки на все YAML-файлы книг, после чего он загружает все YAML-файлы книг из удаленных репозиториев в docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. YAML-файлы книг содержат все URL-адреса ваших файлов Markdown из удаленного репозитория.
- Как только все файлы Markdown будут загружены, инструменты начнут генерацию веб-сайта документации AGL в репозитории docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages], который затем будет развернут.
- Текущий процесс поддержки конвейера сборки и развертывания не удобен для пользователей и разработчиков, особенно для новых участников. Этот рабочий процесс (сборки и размещения) можно значительно упростить и оптимизировать, чтобы разработчики могли сосредоточиться на документировании, а не на поддержке процесса генерации документации и развертывания.