О чём урок
Документация для разработчиков, как правило, более техническая, чем общий контент, но к ней применимы те же принципы тональности: будьте доброжелательны и непринужденны, четки и ясны, и готовы прийти на помощь.
Предполагайте, что разработчики обладают глубоким пониманием концепций программирования. Пропускайте основы и сосредоточьтесь на информации, специфичной для Mistral API, которая поможет им достичь своих целей.
Примеры кода показывают, как использовать элемент API для реализации конкретной функциональности. Они могут включать:
- Простые однострочные примеры, вкрапленные в текст.
- Короткие, самодостаточные примеры, иллюстрирующие конкретный момент.
- Более длинные примеры, иллюстрирующие несколько функций, сложные сценарии или лучшие практики.
Разработчики используют примеры кода для:
- Оценки API на этапе планирования.
- Изучения языка или технологии.
- Написания и отладки кода.
Многие разработчики копируют примеры кода из документации непосредственно в свои проекты.
- Создавайте лаконичные примеры, охватывающие ключевые задачи. Начинайте с простейшего полезного примера и постепенно наращивайте сложность.
- Приоритизируйте часто используемые элементы и элементы, которые могут быть трудны для понимания или сложны в использовании.
- Не используйте примеры кода для иллюстрации очевидных моментов или надуманных сценариев.
- Оставляйте сложные примеры для учебных пособий и пошаговых руководств, где вы можете предоставить пошаговое объяснение.
- Добавьте введение, чтобы описать сценарий и объяснить все, что может быть неясно из кода. Перечислите требования и зависимости.
- Предоставьте разработчикам простой способ копирования и запуска кода.
- Проектируйте код для повторного использования. Помогите разработчикам определить, что нужно изменить. Добавляйте комментарии для объяснения неочевидных деталей — не констатируйте очевидное.
- Показывайте ожидаемый вывод либо в отдельном разделе после кода, либо в комментариях к коду.
- Пишите безопасный код. Никогда не прописывайте учетные данные жестко. Используйте заполнители, такие как os.environ["MISTRAL_API_KEY"] или "your-api-key".
- Показывайте обработку исключений только тогда, когда это неотъемлемая часть примера.
- Всегда компилируйте и тестируйте свой код перед публикацией.
- Каждый блок кода должен иметь языковой тег: ```python, ```typescript, ```bash.
- Используйте стиль кода (обратные кавычки) для всех программных элементов в тексте: имена функций, параметры, методы…
План урока
- Примеры кода
- Планирование примеров кода
- Написание примеров кода
- Правила форматирования кода
- Команды установки менеджера пакетов
Урок входит в полный доступ. Полный текст и видео открываются после оплаты. Первые уроки каждого курса бесплатны.