Введение
Codelab — это интерактивный учебник, написанный на синтаксисе Markdown. Мы публикуем наши codelabs на blocklycodelabs.dev . Codelabs используют смесь естественного языка, примеров кода и снимков экрана для создания более интересного опыта обучения. Целевой пользователь codelab следует и выполняет код по мере чтения.
Написание codelab — отличный способ внести вклад в сообщество. Это способ поделиться своими знаниями и облегчить жизнь следующему разработчику, который столкнется с той же проблемой.
Что делает кодлаб отличной?
Отличная codelab сфокусирована и легко читается. Она четко говорит пользователю, что он будет строить и чему он будет учиться, и проводит пользователя через написание и понимание кода для выполнения определенной задачи.
Процесс
Если у вас есть идея для codelab, вы можете рассказать нам о ней, сделав запрос на функцию в репозитории blockly-samples. Включите описание того, чему вы хотите научить и что вы будете строить в codelab. Мы обсудим и уточним идею. Затем вы можете записать ее и отправить запрос на извлечение . После того, как она пройдет проверку , член команды Blockly опубликует ее.
Советы по написанию
Остальная часть этой страницы представляет собой набор советов и вопросов, которые помогут вам написать лабораторную работу.
Ознакомьтесь с курсом «Техническое письмо 1» для быстрого введения в техническое письмо.
Аудитория
- Кто является целевым читателем?
- Что они уже знают об использовании Blockly?
- Чему они пытаются научиться?
Настраивать
- Какая минимальная настройка необходима пользователю для запуска вашего кода?
Если это будет полезно, вы можете опубликовать начальный код и готовый код в каталоге examples .
Структура
Как и в случае с любым текстом, начните с плана. Это хорошая структура для большинства кодлабов:
- Введение
- Чему вы научитесь
- Что вы построите
- Что вам нужно знать
- Инструкции по установке
- Шаг первый: [Здесь должно быть название]
- Объяснение/мотивация
- Пример кода
- Ожидаемые результаты
- (Необязательно) Дополнительные пояснения
- ...
- Шаг десятый: [Здесь должно быть название]
- Краткое содержание
- Что вы узнали
- Что ты построил
- Дополнительные ресурсы
- Ссылка на готовый код (если имеется)
Хотя шагов может быть больше десяти, если их число приближается к двадцати, стоит рассмотреть возможность разбить их на две лабораторные работы.
Стиль письма
- Используйте разговорный стиль письма.
- Используйте заголовки, чтобы сделать организацию понятной.
- Используйте маркированные списки, чтобы разбить стену текста.
- Используйте изображения и гифки!
Стиль кода
- Вы можете писать на ES5, ES6 или TypeScript, но сообщите читателю, какой язык вы используете, в самом начале.
- Следуйте руководству по стилю Google