На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Электрон
- Технический писатель:
- Мистер Голд
- Название проекта:
- Электронный учебный процесс
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
РЕЗЮМЕ ПРОЕКТА
Electron — один из самых популярных инструментов для создания кроссплатформенных настольных приложений с использованием JavaScript, HTML и CSS. Коллекция приложений, созданных на Electron, насчитывает почти 900 записей, и этот список постоянно растет. Некоторые из самых популярных инструментов разработчика, такие как Visual Studio Code, Atom, Postman, Slack, GitKraken, построены на Electron.
Популярность Electron заключается в простоте обучения и низком пороге входа — каждый, кто знает JavaScript, HTML, CSS, может создать собственное приложение. Огромные общие темпы роста диктуют необходимость создания учебных пособий и руководств по началу работы, которые легко понять и использовать.
Цель проекта — вселить уверенность в разработчиков приложений, которые плохо знакомы с платформой Electron, и предоставить им последовательный и оптимизированный опыт разработки собственных приложений Electron с нуля.
Проблемы проекта
Ниже приводится список наиболее важных проблем, связанных с документацией учебных пособий Electron: 1. Неясная отправная точка и неинтуитивная вводная информация об этапах разработки приложения. 2. Разрозненная и избыточная информация, связанная с процессом разработки приложения. 3. Неорганизованные фрагменты «начала работы». » руководящие инструкции, не имеющие единого источника истины
ПРОЕКТНОЕ ПРЕДЛОЖЕНИЕ
В соответствии с целью проекта и проблемами, изложенными выше, предлагается следующий список улучшений: 1. Обновить существующие руководства. Чтобы сделать первые шаги плавными и последовательными, необходимо обновить следующие документы с постепенным переходом от простого к более сложному: - Среда разработки - Написание вашего первого приложения Electron - Добавление функций в ваше приложение (создайте сводную страницу) - Упаковка приложения и Распространение 2. Реструктуризировать каталог документации. Чтобы показать новым разработчикам, что важно для начала работы и что можно рассматривать как дальнейшие шаги, страница документации должна иметь как визуальное, так и контекстное разделение шагов, чтобы первое приложение работало как можно быстрее. Реструктуризация также включает рекомендации относительно возможных последующих шагов. 3. Организовать и унифицировать документацию по разработке приложений. Все функции должны иметь единый набор инструкций о том, как их установить/включить, как быстро начать работу, как работать с приложением после первого запуска и как его распространять. 4. Включите в документацию репозиторий Electron-Api-Demos. Репозиторий Electron-api-demos содержит набор примеров, показывающих, как добавлять функции в ваше приложение Electron. Эта информация должна быть включена в руководство «Добавление функций в ваше приложение», чтобы соответствовать стратегии единого источника правдивого контента. 5. Интегрируйте примеры Electron Fiddle в документацию. Этот шаг позволит новым разработчикам увидеть, как работает конкретный фрагмент кода, без необходимости повторять шаги вручную. Интеграция включает в себя написание примеров кода для обновленных руководств и добавление кнопки «Запуск в Fiddle» в блоки кода.
ГРАФИК
Период рассмотрения заявки. Познакомьтесь с сообществом и людьми, с которыми можно работать. Изучите руководства и лучшие практики по вкладу сообщества. Сделайте первые взносы. Связывание сообщества. Исследуйте сообщество. Проверьте текущее состояние документации Electron. Выявить слабые места. Неделя 1. Согласуйте с наставниками основные этапы и результаты проекта. Неделя 2. Пересмотрите среду разработки и напишите страницы своего первого приложения Electron. Неделя 3. Пересмотрите архитектуру приложения, добавление функций в ваше приложение, страницы упаковки и распространения приложения. Создайте сводную страницу со списком функций, которые можно добавить в приложение. Неделя 4. Реструктуризация каталога документации. Неделя 5. Подготовьте шаблон того, как электронные API-демо будут интегрированы в основную документацию. Недели 6–7. Миграция репозиторий Electron-api-demos. Неделя 8. Подготовьте шаблон того, как Electron Fiddle будет интегрирован в основную документацию. Напишите первый образец. Недели 9–10 – Интеграция Electron Fiddle в основную документацию. Неделя 11 – Доработка структуры и страниц основной документации после переноса репозитория Electron-api-demos и образцов Electron Fiddle. Неделя 12 – Оценка результатов.
ПОДРОБНАЯ РАЗБИВКА ЭТАПОВ
ПЕРИОД РАССМОТРЕНИЯ ЗАЯВКИ Первая часть периода будет посвящена проверке каналов сообщества и исходного кода, а также установлению контактов с людьми, которые занимаются проектом.
Вторая часть периода будет посвящена проверке культуры вкладов в целом, изучению руководств по вкладам и передового опыта. Это будет время для первых взносов, чтобы увидеть, как работает этот поток.
СВЯЗЬ СООБЩЕСТВА
На этот раз мы будем посвящены более глубокому изучению папки с документацией и ее плана действий. На основе этой информации можно будет выявить слабые места (например, незавершенные или недостающие детали), которые можно улучшить. Создавайте запросы на включение (там, где это возможно), чтобы заполнить пробелы.
НЕДЕЛЯ 1 – НЕДЕЛЯ 2
Первая неделя будет посвящена общению с наставниками с целью согласования ожидаемых этапов и их своевременной реализации.
Вторая неделя будет посвящена пересмотру среды разработки и написанию страниц вашего первого электронного приложения. Для страницы «Среда разработки» это будет включать в себя переписывание общего обзора и корректуру. Для страницы «Написание вашего первого электронного приложения» она будет включать в себя создание последовательного пошагового руководства с четкими начальными и конечными точками, удаление избыточной информации (например, двух похожих блоков кода в разделах «Разработка электронов в двух словах» и «Испытание этого примера»). раздел).
Результаты: Пересмотренные, простые в использовании вводные руководства по быстрому запуску приложений Electron.
НЕДЕЛЯ 3
Эта неделя будет посвящена: 1. Улучшению страницы «Архитектура приложения». Это включает в себя: - переписывание существующей информации в разделах «Основные процессы» и «Процессы рендеринга», чтобы сделать ее простой и интуитивно понятной для начинающего читателя; - добавление визуального представления архитектуры, того, как процессы связаны, как они взаимодействуют, и их основных различий. Примеры визуалов: Раз, Два, Три (низкое качество). 2. унификация информации обо всех функциях, которые вы можете добавить в свое приложение Electron. Это включает в себя переписывание руководств, чтобы в них был единый набор инструкций по установке/включению функции, а также пример того, как эта функция работает. Кроме того, будет создана новая страница (сводка) со списком всех доступных для использования функций. Унифицированные инструкции могут выглядеть следующим образом: - Обзор - Пример: - Пример кода - Наглядный пример (где это возможно)
- упрощение страницы распространения приложений. Это включает в себя: а. объединение упаковки приложений с руководством по распространению приложений b. разделение методов распределения на автоматические и ручные c. взяв в качестве примера автоматического распространения электронно-форж d. возьмите информацию об asar со страницы «Упаковка приложений» и опишите копирование исходных файлов и создание архива asar в качестве примеров ручного распространения. #### НЕДЕЛЯ 4 Эта неделя будет посвящена реструктуризации каталога документации. Оно включает:
1 – разделение существующих справочников как минимум на три категории: а. Быстрый старт б. Изучение основ c. Дополнительные шаги
Категория «Краткий старт» будет содержать базовые руководства (установка, настройка, распространение) для создания последовательной серии руководств, которые позволят новичкам быстро начать работу с нуля. Каждое руководство должно содержать ссылки на предыдущие/следующие руководства серии.
Структура может выглядеть следующим образом: 1. Предварительные требования 2. Установите Electron 3. Создайте базовое приложение 4. Упакуйте/распространите приложение
После завершения раздела «Краткий старт» пользователь узнает основы работы приложений Electron и получит полностью работающее распространяемое приложение Electron.
Категория «Изучение основ» будет содержать руководства, направленные на укрепление знаний об Electron и расширение приложения, созданного в разделах «Быстрый старт». Эти руководства включают в себя: - Архитектуру приложения - Добавление функций в ваше приложение - Шаблоны и интерфейсы командной строки.
Категория «Дополнительные шаги» будет содержать более сложные руководства, направленные на настройку и тонкую настройку вашего приложения Electron: - Тестирование и отладка - Доступность - Безопасность - Обновления.
2 – уменьшение количества страниц документации. Текущая версия документации содержит определенную степень дублирования контента и инструкций без категорий. Например: - Установка и установка Electron при написании первого приложения - Упаковка приложения и упаковка вашего приложения в файл при распространении приложения - Инструкции без категорий в категориях «Подробно» и «Дополнительно»: Предложение: переместите следующие документы в GitHub и исключите из них. основная документация. Эти документы относятся к руководящим принципам разработки Electron, и репозиторий исходных текстов является первым местом для их поиска: - Разработка Electron - Разработка Chromium - Разработка V8 - Проблемы в Electron - Исправления в Electron - Запросы на включение - Структура каталога исходного кода - Тестирование - Кодирование Стиль
Основная идея сокращения состоит в том, чтобы избавиться от подавляющего количества доступных руководств, объединить разрозненные фрагменты информации и предоставить новичкам более структурированную, легко навигируемую и удобную для пользователя версию документации Electron.
НЕДЕЛИ 5–7
Пятая неделя будет посвящена подготовке шаблона (способа) интеграции электронных API-демо в основную документацию. Этот шаблон может выглядеть следующим образом: 1. В основной документации в разделе «Добавление функций в ваше приложение» создайте категории, представленные в электронных-api-демо. 2. Пройдя по каждой из категорий, перенесите демонстрационные примеры в основная документация: - Примеры кода могут быть взяты либо из исходного кода, либо из описания соответствующей функции в приложении - За каждым переданным примером должно следовать соответствующее описание - Каждый дочерний пример (например, Диалог ошибки как дочерний диалоговых окон «Использовать систему») следует перенести под его родительский
ПРИМЕЧАНИЕ №1: есть примеры, которые существуют как в электронных-api-демо, так и в основной документации (например, сочетания клавиш, перетаскивание). В этом случае приоритет должен иметь пример из электронной апи-демоверсии, а пример из основной документации следует игнорировать.
ПРИМЕЧАНИЕ № 2. Многие примеры в приложении Electron-Api-Demos содержат предварительный просмотр описанной функции или функциональности в режиме реального времени. Эта функция будет игнорироваться до интеграции Electron Fiddle на 9-10 неделях.
- Обновите страницу со списком всех доступных для использования функций (которая была создана на третьей неделе) с учетом новой иерархии примеров.
6 и 7 неделя будут посвящены переносу примеров электрон-апи-демо в основную документацию по шаблону, описанному выше. В качестве последнего шага репозиторий Electron-Api-Demos следует удалить или объявить устаревшим.
НЕДЕЛИ 8–10
Неделя 8 будет посвящена подготовке шаблона (способа) интеграции Electron Fiddle в основную документацию. Эта инициатива уже запущена (подробности в выпуске #20442) ребятами из Electron вместе с волонтерами сообщества, но она требует должной доработки.
Чтобы продолжить работу с примерами Fiddle, базовый шаблон может выглядеть следующим образом: 1. Выберите пример из основной документации (например, краткое руководство). На этом этапе документация также должна содержать примеры электронных API-демо; 2. Воссоздайте пример в Electron Fiddle (используя в качестве отправной точки код примера или исходный код); 3. Сохраните Fiddle локально в папке; 4. Переместите пример в /docs/fiddles/[КАТЕГОРИЯ]/[РАЗДЕЛ]/[ДЕМО]. * Список готовых примеров описан в разделе выпуска «Список демо». 5. Добавьте кнопку «Запустить в Fiddle», как описано в первом комментарии к выпуску № 2848.
9 и 10 недели будут посвящены интеграции примеров электронных API-демо (уже конвертированных в Fiddles) в основную документацию по шаблону, описанному выше.
НЕДЕЛЯ 11
Эта неделя будет полностью посвящена завершению проекта написания после успешной миграции репозитория Electron-Api-Demos и образцов Electron Fiddle. Это включает в себя: - проверку того, что все существующие примеры кода имеют кнопку «Запустить в Fiddle» - проверку того, что все существующие примеры кода работают правильно как Fiddles - проверку того, что основная документация больше не ссылается на репозиторий Electron-Api-Demos
НЕДЕЛЯ 12
Завершение выполненной работы. Приемочные проверки.