Предложения по структуре wiki

Контекст

Wiki Uniplant Atomix (репозиторий HelpAsuAutoMix, ~6600 файлов в src/content/docs, sidebar с ~350+ пунктами в astro.config.mjs) объединяет:

описание структуры каталогов и установки;
методику заполнения JSC-моделей;
каталоги типовых блоков (OBJTYPE);
документацию модулей Uniplant Atomix;
операционные руководства по ПТК;
справочные и коммерческие материалы.

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

Что уже хорошо

Главная страница задаёт логику «от требований до сопровождения» и блок «Быстрый старт».
Разделение «данные ↔ инструмент» явно прописано на страницах Модули Uniplant Atomix и JSC. Модели.
Каталоги OBJTYPE (solutions/.../object-types/) с сводными таблицами и objtype-template-mapping — удобная точка входа для поиска блока.
Скрытие детальных статей OBJTYPE из меню (menuMode: "hide") разгружает sidebar, оставляя навигацию через таблицы-каталоги.

Основные проблемы для нового пользователя

1. Несколько «осей» смешаны в одном меню

В sidebar одновременно живут разные типы знаний:

Ось	Пример	Вопрос пользователя
Где лежат файлы	`project-structure`	«Какой каталог создать?»
Как заполнять Excel	`guides/jsc-models`	«Как заполнить лист MKO?»
Что за блоки	`solutions/alpha-trei/...`	«Что такое AiProc3 / 4_20mA?»
Как работает Uniplant Atomix	`uniplant-atomix`	«Как нажать Generate?»
Эксплуатация ПТК	`guides/aspsipt`, admin, SVN	«Как загрузить в контроллер?»
Коммерция / стратегия	`reference`	«Что продаём?»

Новичок не понимает, в какой раздел идти первым.

2. Дублирование темы по разным веткам

Одна предметная область размазана по нескольким разделам:

АСПСиПТ: Руководства АСПСиПТ (операции) + Библиотека АСПСиПТ (каталог AFA) + модули FireSec / HMI-ЗКПС.
АСУТП / ESD: Руководства DCS/ESD + Библиотека АСУТП, АСУЭ + модели ПЛК в solutions/.../plc-models/ и правила в Модель ПЛК.

Пользователь вынужден сам собирать маршрут из 3–4 разделов.

3. Перегруженное боковое меню

Глубокая вложенность (4–5 уровней), почти всё collapsed: true.
Дублирование «Утилиты» — два раза в блоке «Модули Uniplant Atomix».
40+ функций GAP — плоский список в «Руководствах».
В Справочнике — тестовые страницы AiProc3 рядом с материалами по лицензированию.
Смешение языков: Jsc Models, Terms And Abbreviations, Object Types рядом с русскими названиями.

4. Слабые «хабы» и неточные ссылки

Разработанные библиотеки решений — короткая таблица из трёх строк, без сценариев использования.
Руководства АСПСиПТ — только две ссылки на подразделы.
На главной шаг «4. Модули системы» ведёт на /project-structure/libraries/, а не на /uniplant-atomix/ — путаница «библиотеки SVN» vs «модули приложения».
На Структура каталогов часть ссылок вида /libraries/alpha-hmi/ вместо canonical /project-structure/libraries/....

5. Разрыв «каталог ↔ деталь»

Сводные таблицы APUCS/AFA удобны, но детальные статьи OBJTYPE скрыты из меню (menuMode: "hide"). Без поиска пользователь может не понять, что за каждой строкой таблицы — полноценная страница с шаблонами, переменными и mapping.

Целевая mental model

Рекомендуемая схема для onboarding и sidebar — слева направо:

flowchart TB
  subgraph data ["1. Исходные данные"]
    PS[Структура каталогов]
    JSC[JSC Excel-модели]
    OBJ[OBJTYPE-каталог]
  end

  subgraph tool ["2. Uniplant Atomix"]
    SM[Модули приложения]
    GEN[Генерация]
  end

  subgraph result ["3. Результат"]
    PLC[Unimod / FBD]
    HMI[Alpha.HMI / панели]
    DS[DevStudio / Modbus]
  end

  subgraph ops ["4. Эксплуатация"]
    GUIDES[Руководства по ПТК]
    ADM[Администрирование]
  end

  PS --> JSC --> OBJ --> SM --> GEN --> PLC
  GEN --> HMI
  GEN --> DS
  PLC --> GUIDES
  HMI --> GUIDES

Sidebar и обучающие материалы лучше строить по этой цепочке, а не только по историческим путям переноса из старой wiki.

Вариант A. «Карта знаний» по ролям

Объём: минимальные изменения, максимальный эффект для новых пользователей.

Добавить 1–2 обзорные страницы без перестройки дерева файлов.

Страница «С чего начать»

Расширить главную или создать /getting-started/ с маршрутами:

Новый инженер Uniplant Atomix

→ Установка → Настройка → Структура каталогов → JSC. Модели → ПЛК Конфигуратор

Инженер АСПСиПТ

→ Библиотека AFA → Модель ПЛК AFA → заполнение OBJ.* → Генерация Unimod → Экраны ЧМИ

Инженер АСУТП / ESD

→ Каталог APUCS → Модели ПЛК AUCS/DCS/ESD → TagAssignement → Экраны ЧМИ DCS/ESD

Администратор / DevOps

→ Администрирование ПО → SVN → SettingManager

Каждый шаг — с явной подписью типа: данные / инструмент / результат.

Страница-хаб по ПТК

Расширить Альфа-платформа + ПЛК ТРЕЙ таблицей «единая дверь»:

Блок	Ссылки
Каталог типовых блоков	object-types, objtype-template-mapping
Как заполнять модели	guides/jsc-models
Как генерировать	uniplant-atomix, ПЛК Конфигуратор, внешние модули
Операционные инструкции	guides/aspsipt, guides/dcs-esd
HMI	hmi-screens + HMI Менеджер

Плюсы: не требует переноса файлов; только связующие страницы и правка sidebar (вынести хабы наверх).

Объём: средний. Файлы можно оставить на месте через slug.

Предлагаемый верхний уровень меню

Начало работы — install, setting, project-structure, glossary
Методика моделирования — guides/jsc-models (единый блок)
Библиотеки решений — solutions по ПТК
Uniplant Atomix: инструмент — uniplant-atomix
Ввод в эксплуатацию — guides: aspsipt, dcs-esd, panels, SVN, admin
Справочник — GAP, terms, API, commercial

Что убрать или сжать в меню

Действие	Эффект
GAP → только индекс `/reference/gap/` + поиск	−40 пунктов в sidebar
OBJTYPE-детали → только каталоги + mapping	Меньше шума (частично уже так)
Удалить дубль «Утилиты»	Убирает путаницу
Тестовые AiProc3 → `menuMode: hide` или отдельная ветка	Чище «Справочник»
`Terms And Abbreviations` → в «Начало работы»	Глоссарий до первого чтения

Плюсы: меню отражает вопрос пользователя, а не структуру SVN/репозитория.

Вариант C. Сценарные «треки» end-to-end

Объём: средний–высокий. Создать раздел /workflows/ или /scenarios/.

Пример сценария: «Добавить насос Mot2c4s в проект AUCS»

Выбрать OBJTYPE в каталоге APUCS
Заполнить строку на листе OBJ.* — модель ПЛК
Проверить TagAssignement: Mot2c4s
Запустить ПЛК Конфигуратор → workflow
Проверить лог и результаты генерации

Сценарий	Целевая роль
Первый запуск Uniplant Atomix и корневой каталог	Новый инженер
Добавление типового блока в модель ПЛК (AUCS)	Инженер АСУТП
Генерация проекта Unimod для АСПСиПТ	Инженер АСПСиПТ
Настройка диагностики сети (NetSwitches + NetDevices)	Инженер по диагностике

Вариант D. Унификация разделов АСПСиПТ / АСУТП

Объём: высокий. Долгосрочная унификация всех ПТК.

Для каждого направления — единый шаблон раздела:

solutions/alpha-trei/{aspsipt|asutp-asue}/
  index.mdx              — обзор + ссылки на все подразделы
  object-types/          — каталог (есть)
  objtype-template-mapping.mdx
  plc-models/            — модели верхнего уровня (есть)
  plc/                   — FBD-шаблоны (есть)
  operations/            — ключевое из guides/aspsipt (перенос или дублирование)
  hmi/                   — ключевое из guides/.../hmi-screens

Руководства АСПСиПТ остаются для чисто операционных задач (загрузка в контроллер, FireSec), но обзорная страница solutions/aspsipt становится «единой дверью».

Плюсы: один паттерн для всех ПТК.

Минусы: больше работы по переносу и редиректам (в astro.config.mjs уже сотни редиректов).

Вариант E. Быстрые победы без смены IA

Точечные улучшения UX без перестройки информационной архитектуры:

Действие	Эффект
Исправить шаг 4 на главной → `/uniplant-atomix/`	Убирает путаницу Libraries vs Modules
Блок «Вы здесь: данные / инструмент / каталог» в шаблоне OBJTYPE и module pages	Закрепляет mental model
Таблица «Связанные разделы» на каждой index-странице	Как на Состав моделей верхнего уровня, но везде
Terms And Abbreviations в «Начало работы»	AFA, APUCS, OBJTYPE, GAP, AUCS — до первого чтения
Пометки «в подготовке» в sidebar для CodeSys / Weintek	Не обещать контент, которого нет
Усилить поиск (Pagefind) по именам OBJTYPE	Критично при скрытых из меню страницах
«Следующий шаг» в конце статей (LinkCard / pagination)	Снижает «тупик» после сводной таблицы
Исправить canonical-ссылки на Структура каталогов	Единообразие URL

Приоритет	Вариант	Оценка трудозатрат
1	E — быстрые победы (ссылки, шаблоны)	1–2 дня
2	A — хабы и learning paths	1–2 дня контента
3	B — упрощение sidebar	2–3 дня
4	C — 2–3 сквозных сценария (AUCS, АСПСиПТ)	3–5 дней
5	D — унификация всех ПТК	долгосрочно

Чек-лист для приёмки улучшений

После внедрения каждого этапа проверить:

Новый пользователь за 3 клика от главной попадает в свой сценарий (роль × ПТК).
На главной нет ссылок, путающих «Libraries (SVN)» и «Модули Uniplant Atomix».
Из каталога OBJTYPE видна связь с детальной статьей и с mapping.
Из статьи OBJTYPE есть путь к модели ПЛК, модулю генерации и логу.
Sidebar не содержит дублей и тестового контента в production-ветке меню.
Глоссарий доступен из «Начало работы» до чтения специализированных разделов.

Связанные материалы

Материал	Назначение
Модули Uniplant Atomix: обзор	Граница «инструмент vs данные»
JSC. Модели	Методика исходных данных
Разработанные библиотеки решений	Каталоги по ПТК
Uniplant Atomix для заказчика	Продуктовый контекст
Услуги и лицензирование Uniplant Atomix	Коммерческий контекст