Пример документации, которую стоит читать самостоятельно

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

Я захотел развернуть на своей виртуалке инстанс SilverBullet, простого клиент-серверного ПО для ведения базы знаний. Я составил план для агента, в котором ему нужно было прочитать документацию по ссылке, подготовить окружение и выбрать способ деплоя, при котором защита базы знаний будет обеспечиваться не только за счет аутентификации по паролю при условии доступа как минимум с трех устройств с разными ОС. Этого явно недостаточно, открытый порт, доступный из интернета —постоянная мишень для тысяч (или миллионов?) ботов, сканирующих и пытающих достучаться до любого открытого эндпойнта.

Агент (Kimi k2.6+Kimi CLI) предложил несколько вариантов, причем больше всего ему нравилась идея использовать Tailscale с бесплатным аккаунтом для создания VPN в смысле настоящей виртуальной частной сети. Идея в общем-то неплохая, но в основе Tailscale лежит блокируемый у нас WireGuard, а ещё я в принципе не хочу завязываться на внешнюю систему для контроля доступа.

Поэтому я отклонил все предложенные варианты и решил в стиле старой школы самостоятельно прочитать доку. Так как сам по себе SilverBullet —это ПО для управления базами знаний, его документация не содержит какой-то специфики для создания защищенного соединения, этим должен заниматься пользователь. Зато в документации нашлась секция со ссылками на посты от комьюнити, один из которых показывал, как настроить знакомый мне сервер Caddy и самостоятельно управлять сертификатами, чтобы только доверенные устройства могли установить TLS-соединение.

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

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