# General Translation Blog: Проектируем документацию для людей
URL: https://generaltranslation.com/ru/blog/designing-docs-for-humans.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Почему дизайн по-прежнему важен в эпоху ИИ и какими принципами оформления документации мы руководствуемся, чтобы избавить читателя от лишнего информационного шума.
Authors: Kevin Liu, Taylor Fang
Published: 2026-09-17
## Зачем проектировать документацию?
Документация — открытая проблема веб-дизайна. Повсюду встречаются как удачные подходы, так и антипаттерны, до бесконечности растиражированные готовыми шаблонами. Шаблоны — это быстро и просто, но возникает риск относиться к документации как к чему-то второстепенному, а не как к ключевой части опыта работы с продуктом, которую нужно проектировать под конкретного пользователя. К тому же общепринятые решения часто перегружены визуальными эффектами. Мы считаем, что сайтам документации нужен **более простой опыт чтения, сосредоточенный на содержании**, а изощрённые решения стоит оставить маркетинговому сайту (здесь мы опираемся на философию [создателя Fumadocs](https://generaltranslation.com/blog/fuma-nama)).
Но в мире, где большинство читателей документации, как и её авторов, — агенты, **стоит ли по-прежнему заниматься дизайном сайта документации?** Зачем вообще вкладываться в удобочитаемость для человека и визуальное оформление?
Мы убеждены, что интуитивно понятный, продуманный интерфейс документации становится тем важнее, чем больше вокруг низкокачественного ИИ-контента. Это убеждение рождается из любви к ремеслу дизайна и одержимости тем, как воспринимается наш продукт. Но есть и простое наблюдение: **люди по-прежнему смотрят и читают документацию**. Да, агенты массово исполняют код, но статистика по объёмам отражает не всё. Люди всё так же заходят на сайты документации, чтобы разобраться в продукте и оценить его. И людям всё больше нужны интерфейсы, которые убирают ментальный шум и направляют внимание на главное.
К редизайну документации мы подошли с чистого листа, оттолкнувшись от параллельных пользовательских сценариев, которые разбирали в [переработке нашего контента](https://generaltranslation.com/blog/rewriting-our-docs). Примитивов документации совсем немного: навигация, поиск, элементы управления, ссылки и содержание. Мы расположили их так, чтобы линий было меньше, а свободного пространства — больше, ради более чистого визуального восприятия, и взяли за основу документационный фреймворк с открытым исходным кодом [Fumadocs](https://generaltranslation.com/blog/fuma-nama) — ради максимальной компонуемости.
Мы много работаем над текстами и хотим, чтобы их читали. Наша постоянная цель — спроектировать и поддерживать сайт документации, на котором читать удобно и даже приятно. По пути мы выработали несколько ключевых принципов дизайна. Первый из них — использовать знакомый и понятный интерфейс.
## Интуитивный поток и направление
Документация помогает пользователям выстроить ментальную модель продукта и принципов его работы — об этом мы [писали](https://generaltranslation.com/en-US/blog/rewriting-our-docs) в статье нашего блога о реструктуризации контента документации. Дизайн вырос из тех же базовых принципов: продуманная и осмысленная структура, постепенное раскрытие сложности и возможностей настройки, а также детали, которые не отвлекают и даже остаются незаметными.
Каждая область экрана **соответствует единому действию или результату**, поэтому функции оказываются там, где пользователи и ожидают их найти. (Мы заметили, что у части пользователей есть устойчивые предпочтения по визуальным темам, поэтому переключатель режима присутствует сразу в двух местах.)
Страница также поддерживает интуитивный поток, **подводя пользователей к тому, чего они хотят достичь**.
Документация подсвечивает ссылки на действия, которые могут понадобиться пользователям: перейти в Changelog за обновлениями, задать вопрос в поддержку или запросить демонстрацию продукта.
## Избавляемся от ментального шума
Интерфейсы становятся всё более перегруженными. Такие элементы, как «надзаголовки», случайные анимации, двигающиеся сразу в нескольких плоскостях, и лишние блоки (со скруглёнными углами) — верные признаки дизайна, сделанного ИИ. **Следствие этого визуального шума — сопутствующий ему шум ментальный.** Когда каждый компонент существует просто потому, что существует, без продуманного размещения и связи с другими компонентами, смысл растворяется.
Поэтому наша первая задача — **убрать ментальный шум**. То есть удалить лишние элементы; в нашем случае — множество избыточных линий, ссылок и кнопок.
Но это также означает структурирование, реорганизацию и радикальное упрощение. В частности, мы объединили навигационные поверхности — карту, которая **упорядочивает ментальные концепции сайта и указывает на них**.
Наша боковая панель теперь представляет собой единственный аккордеон. Звучит не слишком революционно, но для сайтов документации это стало редкостью: обычно там показывают сразу несколько панелей навигации по разделам в разных местах — и по вертикали, и по горизонтали.
CI следит за соблюдением чёткой иерархии боковой панели, не позволяя ей превратиться в пугающий список ссылок и пунктов на одном уровне. И эта панель устойчива: переход по ссылке не меняет её содержимое целиком и не заставляет вас потерять место, к которому вы захотите вернуться.
## Направляя взгляд
Интуитивный поток также подсказывает пользователю, как двигаться по интерфейсу. Мы хотели естественно вести взгляд пользователя к важным областям, **выстроив более выраженную визуальную иерархию**: для навигации, элементов управления, содержимого и действий.
a) Использование значков в важных местах, чтобы разбивать сплошные полотна текста.
b) Добавление разделителей между текстовыми блоками, чтобы сгруппировать содержимое и сделать границы разделов заметнее.
c) Разное оформление текста, в том числе курсив (которого документация обычно побаивается) и снижение насыщенности до 400 для основного текста.
Особенно нам хотелось оставить побольше воздуха, чтобы содержимому было чем «дышать», — вдохновением послужила [документация Linear](https://linear.app/docs). Редизайн страницы Quickstarts наглядно показывает, как эти принципы работают вместе.
## Особый стиль GT
Сайты документации — это всё же веб-страницы, и они не должны выглядеть безжизненно. Стараясь не переусердствовать с оформлением и не отвлекать внимание от содержимого, мы всё же добавили детали «микро-UI», которые помогают вписать документацию в эстетику и мир бренда GT.
Мы придумали ненавязчивое взаимодействие для [культового компонента оглавления Fumadocs](https://generaltranslation.com/en-US/blog/fuma-nama/#the-fumadocs-design-credo). Он работает с серверным рендерингом как SVG-маска: отступ вложенности 12px и едва заметный синий ползунок, который следует за указателем. Мобильная выдвижная панель рисует ту же геометрию статически, ведь при касании наведения не бывает.
Ту же маску мы применили к боковой панели. Пройдите по разделу сверху вниз — и синий ползунок заскользит по направляющей, изгибаясь внутрь там, где дерево ветвится, и следуя за указателем строка за строкой.
Мы также тщательно подобрали остальные элементы интерфейса, чтобы уйти от признаков дизайна, сгенерированного ИИ. Сплошные значки мы используем везде, где значок несёт смысл, а тонкие контурные глифы оставляем для элементов управления, например поиска и копирования. Скругление у блоков стало меньше. Мы сделали единообразные полосы прокрутки в боковой панели, блоках кода и меню вместо стандартной смеси нативных и накладных полос. А для переключателя языков применяем собственные SVG-флаги вместо эмодзи-флагов, чтобы сохранить матовую визуальную иконографию и не расходиться с нашей главной страницей.
И, конечно, локализация нашей документации должна быть первоклассной: с сохранением отступов, выравнивания и порядка.
## Чёрный список
По ходу работы мы составили «чёрный список» замеченных антипаттернов.
* Надзаголовки (eyebrow text)
* Случайный лишний пояснительный текст
* Чрезмерно скруглённые блоки
* Контурные, а не сплошные значки
* Разные отступы, никак не связанные с важностью содержимого
* Нелокализованная документация (!)
* Несколько блоков навигации, разбросанных по странице
* Боковые панели, раскрывающиеся будто до бесконечности
* Боковые панели, которые меняются при нажатии
* Боковые панели, в которых теряешь, где находишься
Разумеется, мы постоянно работаем над оформлением нашей документации и будем рады любым отзывам. Удачного проектирования документации!
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.