Примеры кода, которые можно повторить
Разделите команды, вводные данные и результат, чтобы читатель смог выполнить пример самостоятельно.
Хороший пример в документации выдерживает копирование. Читатель может понять, где выполнить команду, какой файл нужен, что должно появиться и как распознать ошибку. Подсветка синтаксиса помогает заметить структуру, но сама по себе не делает пример воспроизводимым. Для первого примера подсчитайте записи в небольшом текстовом файле. Здесь не понадобится сеть или установка дополнительных пакетов.
Сначала опишите входные данные
Представьте заметку для коллеги, который хочет посчитать задачи в учебном списке. Укажите, что понадобится Python 3 и обычный текстовый файл в кодировке UTF-8. Предложите создать отдельную учебную папку. В ней будет лежать файл tasks.txt, а рядом count_tasks.py. Если читатель запустит программу из другой папки, относительный путь будет разрешён от текущего рабочего каталога. Поэтому фраза «откройте терминал в папке с обоими файлами» важнее абстрактного «запустите пример».
Для входного файла подойдёт небольшой набор. Пустая строка здесь нужна, чтобы можно было проверить обработку пустых строк, а не только общий результат.
Проверить первую главу
Подготовить вопросыРазведите код, команду и вывод
Блок с ограждением из обратных кавычек сохраняет строки кода. Сразу после открывающего ограждения можно указать имя языка. Конкретный редактор решает, будет ли подсветка и какие языки он знает. Для простого файла данных и ожидаемого вывода подойдёт текстовый блок. Читателю станет легче различать части, если подписи перед ними прямо говорят, куда их вставить.
Сохраните этот код в файле count_tasks.py.
from pathlib import Path
lines = Path("tasks.txt").read_text(encoding="utf-8").splitlines()
tasks = [line for line in lines if line.strip()]
print(len(tasks))Выполните команду в терминале.
python count_tasks.pyНа некоторых системах команда запуска Python 3 называется python3 или доступна через установленный запускатель py. Лучше объяснить это один раз возле команды. Не добавляйте в копируемый блок приглашение оболочки, например знак доллара, имя пользователя или текущий путь. Такие символы на экране терминала показывают, что оболочка готова принять команду, но копировать их вместе с командой не нужно.
Для указанного файла программа должна вывести число два.
2Не соединяйте ввод и вывод в один блок без пояснения. Человек может скопировать весь фрагмент и получить ошибку из-за строки результата. Если нужен именно пример сеанса, так его и назовите, а команды для самостоятельного запуска продублируйте отдельным коротким блоком.
Опишите ошибку и следующее действие
Когда файл отсутствует, пример закончится ошибкой чтения. Для руководства достаточно назвать диагностический признак FileNotFoundError и предложить проверить имя файла и текущую папку. Не просите читателя угадывать по полной трассировке, какая часть важна. Если разные системы показывают разный путь в сообщении, не обещайте совпадение каждой строки. Существенны тип ошибки и имя искомого файла.
В самом примере можно было бы добавить обработку ошибок, проверку аргументов и конфигурацию. Это уже другая учебная задача. Здесь цель состоит в том, чтобы показать расчёт на известном входе. Небольшой код проще проверить, а границы использования можно объяснить рядом. Если фрагмент записывает или удаляет файлы, для демонстрации используйте отдельную временную папку и явно назовите затрагиваемые данные.
Проверьте публикацию как читатель
Откройте готовую страницу и скопируйте код и команду с неё, а не из исходника. Вставьте их в новую папку. Убедитесь, что отступы в Python сохранились, кавычки не превратились в типографские, а строки данных не слиплись. Первый запуск должен вывести число два. Добавьте ещё одну непустую строку и повторите запуск. Теперь ожидается три. Эта вторая проверка показывает, что результат зависит от файла, а не случайно совпадает с примером.
Откройте страницу на телефоне или в узком окне. Проверьте, что видны начало и конец каждой строки. Если самая важная команда требует горизонтальной прокрутки, упростите её либо разделите объяснение на несколько шагов. Переносить строку кода только для красоты рискованно, если язык или оболочка воспринимает перенос как конец команды. У сложной инструкции дайте читателю краткую цель до блока и объяснение результата сразу после него. Тогда фрагмент остаётся полезным и при отключённой подсветке.
Покажите, что результат меняется на границах
Подготовьте второй входной файл без задач. Оставьте в нём только пустые строки и пробелы. После запуска результат должен быть нулём. Теперь добавьте строку с пробелом перед словом. Она считается задачей, потому что после удаления пробелов текст остаётся непустым. Так читатель видит, что правило относится к содержимому, а не к позиции символа. Если задачей должна считаться только строка с определённым префиксом, это другое условие. Сформулируйте его до примера и подберите отдельную пару входов. Для проверки документации удобно хранить маленькие данные рядом с текстом. Тогда редактор может повторить опыт после переименования файла или обновления инструкции и заметить, что часть исходных предпосылок изменилась. Если входные данные передают отдельным файлом, проверьте, что ссылка скачивает сам файл, а не страницу с предпросмотром.