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

Эта статья дополняет Руководство по стилю документации YDB. Она объясняет текущие директории верхнего уровня документации и какой контент принадлежит каждой из них. Как правило, большинство разделов верхнего уровня фокусируются либо на конкретной целевой аудитории (если названы «Для ...»), либо на конкретном жанре.

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

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

Общие правила

• Документация YDB многоязычная, и структура файлов для каждого языка должна быть согласованной для корректной работы переключателя языков. Содержимое файлов также должно быть максимально близким между языками. Единственным исключением является папка «Публичные материалы», которая намеренно содержит разный контент для разных языков. Все остальные расхождения между языками считаются техническим долгом.
• Поддерживайте консистентность между структурой файлов в репозитории, URL-адресами в адресной строке и папками в боковой панели. Исторически они были независимыми, но опыт показал, что несогласованности приводят к путанице и проблемам с навигацией. Документация постепенно переходит к единой структуре.
• Если имя файла или папки содержит несколько слов, используйте - вместо _ в качестве разделителя, если имя не является ключевым словом, включающим подчёркивания (например, имена разделов конфигурации).
• При переименовании или перемещении любой статьи обязательно добавьте перенаправление со старого URL на новый в redirects.yaml.

Список папок верхнего уровня

• Начало работы. Руководство для начинающих, объясняющее, как настроить одноузловой сервер YDB и выполнить на нём первые запросы.
• Концепции. Высокоуровневый теоретический обзор YDB как технологии, охватывающий его функции, терминологию и архитектуру. Предназначен для широкой аудитории с минимальными предварительными знаниями, включая руководство компаний и лиц, принимающих решения.
• Для DevOps. Папка для DevOps-инженеров, отвечающих за настройку и эксплуатацию кластеров YDB. Большинство контента состоит из практических руководств для конкретных задач, связанных с кластером. Поскольку YDB поддерживает несколько вариантов развёртывания, руководства, различающиеся в зависимости от метода развёртывания, размещаются в соответствующих подпапках (Ansible, Kubernetes или вручную), каждая из которых следует согласованной внутренней структуре. Здесь также включена теоретическая информация, специфичная для этой роли.
• Для разработчиков. Папка для разработчиков приложений, работающих с YDB. В основном состоит из практических руководств и теории.
• Для инженеров безопасности. Папка для инженеров по безопасности, отвечающих за защиту и аудит кластеров YDB и приложений, взаимодействующих с ними. Содержит в основном практические руководства и теорию, специфичную для роли.
• Для контрибьюторов. Папка для участников основной команды разработки самого YDB и внешних контрибьюторов. Она объясняет различные процессы вокруг разработки YDB и предоставляет более глубокое понимание того, как работают некоторые компоненты. В основном теория с несколькими практическими руководствами.
• Справка. Подробный раздел со справкой по различным аспектам YDB. Подразумевается, что читатели будут попадать сюда в основном через поиск по мере необходимости или ссылки из других разделов. Основная цель — полнота, чтобы любая тема могла быть найдена через точные совпадения ключевых слов или их описания. Три основных сценария использования этого раздела:
  • Поиск значения незнакомых ключевых слов, функций, настроек, аргументов и т.д.
  • Поиск правильного синтаксиса для запросов, работы с SDK или конфигурационных файлов.
  • Использование как цели для внутренних ссылок, когда другие статьи документации упоминают функциональность без подробного объяснения.
• Рецепты. Мини-руководства, объясняющие конкретные задачи с YDB, часто с примерами и фрагментами кода. Эта папка существует в основном по историческим причинам, так как большая часть её содержимого могла бы быть размещена либо в папках «Для ...», либо в «Вопросы и ответы».
• Диагностика проблем. Смесь теории о потенциальных проблемах, возможных при работе кластерами YDB и взаимодействующими с ними приложениями, а также практических руководств для диагностики и их устранения.
• Вопросы и ответы. Раздел в стиле StackOverflow с часто задаваемыми вопросами. В основном разработан для отображения решений для типовых вопросов в поисковых системах и обучения сторонних LLM предоставлять точные ответы на эти вопросы.
• Публичные материалы. Коллекция ссылок на видео и статьи о YDB. Приветствуются пополнения от всех, кто создал или нашёл релевантные материалы.
• Загрузки. Коллекция ссылок для скачивания исполняемых файлов YDB.
• Список изменений. Заметки о выпуске для каждой новой версии сервера YDB и других связанных приложений.