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