Жанры документации YDB

Эта статья дополняет Руководство по стилю документации YDB, описывая основные жанры статей, используемые в документации YDB. Понимание этих жанров помогает контрибьюторам размещать новый контент в соответствующем разделе и поддерживать консистентную структуру материалов.

Теория

Основная цель для читателя: построить прочный фундамент знаний и прийти к пониманию основных концепций, архитектуры и принципов, на которых работает YDB.

Теоретическая документация:

  • вводит ключевые концепции и терминологию;
  • объясняет, как система работает как с точки зрения пользователя, так и изнутри;
  • предоставляет высокоуровневые обзоры компонентов системы;
  • помогает пользователям понять «почему» за архитектурными решениями;
  • может быть нацелен либо на широкую аудиторию с минимальными предварительными знаниями, либо на конкретную роль;
  • может включать диаграммы и другие визуализации для помощи в передаче информации.

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

Руководство

Основная цель для читателя: выполнить конкретную практическую задачу или реализовать определённое решение с помощью YDB, следуя инструкциям.

Руководства — это практические пошаговые инструкции, которые помогают пользователям достичь конкретной цели с помощью YDB. Каждая статья в этом жанре:

  • предоставляет чёткую цель и последовательные инструкции для её достижения;
  • включает конкретные примеры и команды;
  • фокусируется на практической реализации;
  • освещает конкретные сценарии использования;
  • может включать скриншоты для иллюстрации шагов.

Руководства в основном находятся в папках, специфичных для ролей, таких как YDB для DevOps-инженеров, YDB для разработчиков приложений и YDB для инженеров по безопасности, а также в разделе Диагностика проблем.

Справочник

Основная цель для читателя: найти дополнительную информацию по конкретной узкой теме, связанной с YDB.

Справочная документация предоставляет всестороннюю, подробную информацию о компонентах YDB, запросах, API, параметрах конфигурации, CLI-командах, страницах UI и многом другом. Этот жанр:

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

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

FAQ

Основная цель для читателя: быстро найти ответы на распространённые вопросы, возникающие при работе с YDB.

Документация часто задаваемых вопросов (FAQ) отвечает на общие вопросы о YDB в формате прямых вопросов и ответов на них. Этот жанр:

  • обращается к конкретным, часто задаваемым вопросам;
  • предоставляет краткие, сфокусированные ответы;
  • организован по темам или категориям;
  • помогает пользователям быстро находить решения типовых проблем;
  • оптимизирован для обнаружения поисковыми системами или LLM.

Контент FAQ в основном находится в разделе Вопросы и ответы про YDB и разработан для помощи пользователям, которые ищут конкретные решения для типовых ситуаций.

Рецепт

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

Рецепты — это короткие, сфокусированные мини-руководства, которые демонстрируют, как выполнять конкретные задачи с помощью YDB. Этот жанр:

  • предоставляет краткие решения для конкретных проблем;
  • включает фрагменты кода и примеры;
  • акцентирует внимание на практической реализации;
  • более узко сфокусирован, чем полноценные руководства;
  • часто следует формату проблема-решение.

Рецепты в основном находятся в разделе Рецепты по работе с YDB, хотя похожий контент может также появляться в папках, специфичных для роли.

Заметки о выпуске

Основная цель для читателя: быть в курсе новых функций, улучшений, исправлений ошибок и критических изменений в выпусках YDB.

Заметки о выпуске документируют изменения, улучшения и исправления в каждой новой версии YDB. Этот жанр:

  • перечисляет новые функции и улучшения;
  • документирует исправления ошибок и решённые проблемы;
  • выделяет критические изменения и устаревшие функции;
  • предоставляет инструкции по обновлению при необходимости;
  • организован хронологически по номеру версии.

Заметки о выпуске находятся в разделе Список изменений YDB Server и помогают пользователям понять, что изменилось между версиями, и решить, обновляться ли.

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

Коллекции ссылок предоставляют курированные списки ресурсов, связанных с YDB. Этот жанр:

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

Коллекции ссылок в основном находятся в разделах Видеозаписи и Загрузки YDB и выступают входными точками к внешним ресурсам о YDB.

Предыдущая
Структура
Следующая
Общая схема