Написание хорошей кодовой лаборатории

Введение

Codelab — это интерактивное руководство, написанное с использованием синтаксиса уценки. Мы публикуем наши кодовые лаборатории на сайтеblocklycodelabs.dev . В Codelabs используется сочетание естественного языка, примеров кода и снимков экрана, чтобы сделать обучение более интересным. Целевой пользователь лаборатории кода следит за ним и запускает код по мере его чтения.

Написание лаборатории кода — отличный способ внести свой вклад в сообщество. Это способ поделиться своими знаниями и облегчить жизнь следующему разработчику, который столкнется с той же проблемой.

Что делает хорошую кодовую лабораторию?

Отличная кодовая лаборатория сфокусирована и удобочитаема. Он четко сообщает пользователю, что он будет создавать и чему он научится, а также помогает пользователю писать и понимать код для выполнения конкретной задачи.

Процесс

Если у вас есть идея для лаборатории кода, вы можете рассказать нам о ней, сделав запрос на добавление функции в репозиторий блочных образцов. Включите описание того, чему вы хотите научить и что вы будете создавать в лаборатории кода. Мы обсудим и доработаем идею. Затем вы можете написать это и отправить запрос на вытягивание . После прохождения проверки член команды Blockly опубликует его.

Советы по написанию

Остальная часть этой страницы представляет собой набор советов и вопросов, которые помогут вам при написании лаборатории кода.

Ознакомьтесь с техническим письмом One , чтобы получить краткое введение в техническое письмо.

Аудитория

  • Кто является целевой читатель?
  • Что они уже знают об использовании Blockly?
  • Чему они пытаются научиться?

Настраивать

  • Какова минимальная настройка, необходимая пользователю для запуска вашего кода?

Если это полезно, вы можете опубликовать начальный и завершенный код в каталоге examples .

Состав

Как и в любом письме, начните с плана. Это хорошая структура для большинства лабораторий кода:

  • Введение
    • Что вы узнаете
    • Что ты построишь
    • Что тебе нужно знать
    • Инструкции по настройке
  • Шаг первый: [Здесь находится название]
    • Объяснение/мотивация
    • Пример кода
    • Ожидаемые результаты
    • (Необязательно) Дополнительные пояснения
  • ...
  • Шаг десятый: [Здесь находится название]
  • Краткое содержание
    • Что вы узнали
    • Что ты построил
    • Дополнительные ресурсы
    • Ссылка на готовый код (если есть)

Хотя у вас может быть более десяти шагов, если вы набрали двадцать, вам следует подумать о том, чтобы разбить его на две лаборатории кода.

Стиль письма

  • Используйте разговорный стиль письма.
  • Используйте заголовки, чтобы сделать организацию понятной.
  • Используйте маркированные списки, чтобы разбить стены текста.
  • Используйте изображения и гифки!

Стиль кода