На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Фонд Linux
- Технический писатель:
- бор
- Название проекта:
- Переработать хостинг и создание документации, а также реструктурировать начальные страницы и руководства для разработчиков.
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание проекта
Абстрактный :
Документация предназначена для помощи конечным пользователям и разработчикам в использовании продукта или услуги. Хорошая документация очень важна, поскольку она дает пользователям возможность узнать, как использовать программное обеспечение, его функции, советы и рекомендации, а также решать распространенные проблемы, возникающие при использовании программного обеспечения. Это также снижает затраты на поддержку и является частью корпоративной идентичности продукта с открытым исходным кодом: хорошая документация является признаком работоспособности продукта и команды разработчиков.
Без хорошей документации пользователь может не знать, как эффективно и результативно выполнять вышеуказанные действия. Документация может сыграть решающую роль в обеспечении успеха продукта, поскольку хорошая коммуникация есть и всегда будет в основе любого бизнеса или продукта, а хорошая документация просто берет эту коммуникацию и помещает ее в управляемую структуру, к которой каждый может получить доступ для достижения успеха.
Каждому сайту документации необходим хороший конвейер рабочих процессов создания и хостинга. В такой организации, как AGL, с несколькими версиями и большим количеством подробной документации файлы документации (уценки) распределены по нескольким репозиториям, что делает задачу их обслуживания и обновления невероятно сложной. и требует много времени.
Текущее состояние:
- Веб-сайт документации AGL основан на наборе файлов уценки, полученных из различных репозиториев.
- Страницы документов в настоящее время размещаются в отдельных источниках в виде уценки с использованием движка проекта Cordova.
- Это приводит к настройке четырех репозиториев для процесса сборки документации и хостинга:
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]: содержит шаблон веб-сайта Jekyll.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools]: содержит инструменты для автоматического создания технического веб-сайта из файлов Markdown.
- Исходники документации [https://github.com/automotive-grade-linux/docs-sources]: Источник (уценки [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs ]) для общих документов, справочников.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages]: развернутый репозиторий страниц GitHub для сайта документации [https://gist.github.com/growupboron/docs. carslinux.org].
- Инструмент (скрипт), доступный в docs-tools [https://github.com/automotive-grade-linux/docs-tools], заботится о сборе и создании шаблонов всех файлов уценки в соответствии с 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-адреса ваших файлов уценки из удаленного репозитория.
- Как только все файлы уценки будут получены, инструменты создают веб-сайт документации AGL на страницах docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages], что соответственно развернут.
- Текущий процесс поддержки конвейера не удобен для пользователей и разработчиков, особенно для новых участников. Этот конвейер рабочего процесса (сборки и хостинга) можно упростить и оптимизировать, чтобы разработчики могли сосредоточиться на части документации, а не поддерживать рабочий процесс создания и развертывания документации.