На этой странице содержится подробная информация о проекте технического написания, принятом для участия в 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
Завершение выполненной работы. Приемочные проверки.