Перейти к основному содержимому

Как работать с этой документацией

Документация находится в Docusaurus-приложении: apps/docs.

Запуск локально​

cd apps/docs
npm run start -- --host 127.0.0.1 --port 3103 --no-open

Открыть:

http://127.0.0.1:3103/

Сборка​

cd apps/docs
npm run build

Где лежат страницы​

apps/docs/docs

Основные разделы:

  • architecture — как устроена система;
  • domain — предметные контуры;
  • backends — Laravel/backend/admin logic;
  • frontend — public UI, Livewire, Filament;
  • operations — запуск, поддержка, процессы;
  • reference — карта файлов и БД;
  • security — риски и audit notes.

Как добавлять страницу​

  1. Создать .md файл в нужной папке.
  2. Добавить frontmatter:
---
title: Название страницы
sidebar_position: 1
---
  1. Добавить страницу в sidebars.js, если sidebar не подхватил её автоматически или нужен точный порядок.
  2. Запустить Docusaurus build.

Как поддерживать качество документации​

Для каждой новой фичи обновляйте минимум один из разделов:

  • изменился route — обновить Routes и middleware;
  • изменилась модель/таблица — обновить Миграции и модель данных;
  • изменился каталог — обновить Домен: современный каталог;
  • изменился roadmap — обновить Домен: roadmap / program;
  • изменилась админка — обновить Filament-админка;
  • изменился cron/job — обновить Jobs, очереди и cron;
  • появился риск — обновить Карта рисков и неочевидных мест.

Стиль документации​

Писать простыми словами:

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

Не писать только “что делает класс”. Разработчику важнее понять, где начинается поток, где источник истины и что может сломаться.