# Документация проекта

> Требования к документации и шаблоны для студенческих проектов

_Источник: https://sii.sergeivolchkov.ru/materials/labs/documentation-guide_





## Что лежит в репозитории [#что-лежит-в-репозитории]

Проект курса — это не только код. Половина того, за что ставится оценка,
живёт в `docs/`, и появляется там по ходу лаб, а не в последний вечер:

<Files>
  <Folder name="docs">
    <Folder name="use-cases">
      <File name="UC-01-upload-material.md" />

      <File name="UC-02-questions.md" />
    </Folder>

    <Folder name="diagrams">
      <File name="c4-context.puml" />

      <File name="c4-container.puml" />
    </Folder>

    <Folder name="adr">
      <File name="ADR-001-stack.md" />

      <File name="ADR-002-model-choice.md" />
    </Folder>

    <File name="agent-workflow.md" />
  </Folder>

  <Folder name="evals">
    <File name="dataset.yaml" />

    <File name="test_questions.py" />
  </Folder>

  <Folder name="prompts" />

  <Folder name="src" />

  <Folder name="tests" />

  <File name="AGENTS.md" />

  <File name="README.md" />

  <File name="compose.yml" />

  <File name="Dockerfile" />

  <File name=".env.example" />
</Files>

Проверка на защите простая: по этому дереву любой человек со стороны
должен суметь запустить проект и понять, почему он устроен именно так.
`.env.example` — потому что `.env` в репозиторий не попадает никогда.

## Обязательные материалы [#обязательные-материалы]

Каждый проект должен содержать следующие документы:

<div className="grid grid-cols-1 md:grid-cols-2 gap-6 my-8">
  <Card className="border-2 border-blue-600/30">
    <CardHeader>
      <div className="flex items-center gap-3">
        <div className="w-12 h-12 bg-blue-600 flex items-center justify-center">
          <Github className="h-6 w-6 text-white" />
        </div>

        <CardTitle className="text-lg">
          README.md
        </CardTitle>
      </div>
    </CardHeader>

    <CardContent>
      <div className="text-sm text-muted-foreground mb-4">
        Полное описание проекта в GitHub репозитории с инструкциями по запуску
      </div>

      <div className="flex gap-2">
        <Badge variant="outline" className="text-xs">
          Обязательно
        </Badge>

        <Badge variant="outline" className="text-xs bg-blue-600/10">
          С Лабы 1
        </Badge>
      </div>
    </CardContent>
  </Card>

  <Card className="border-2 border-green-600/30">
    <CardHeader>
      <div className="flex items-center gap-3">
        <div className="w-12 h-12 bg-green-600 flex items-center justify-center">
          <Presentation className="h-6 w-6 text-white" />
        </div>

        <CardTitle className="text-lg">
          Презентация
        </CardTitle>
      </div>
    </CardHeader>

    <CardContent>
      <div className="text-sm text-muted-foreground mb-4">
        PDF презентация для Demo Day (10-12 слайдов на 10 минут)
      </div>

      <div className="flex gap-2">
        <Badge variant="outline" className="text-xs">
          Обязательно
        </Badge>

        <Badge variant="outline" className="text-xs bg-green-600/10">
          Лаба 6
        </Badge>
      </div>
    </CardContent>
  </Card>

  <Card className="border-2 border-red-600/30">
    <CardHeader>
      <div className="flex items-center gap-3">
        <div className="w-12 h-12 bg-red-600 flex items-center justify-center">
          <Video className="h-6 w-6 text-white" />
        </div>

        <CardTitle className="text-lg">
          Видео демо
        </CardTitle>
      </div>
    </CardHeader>

    <CardContent>
      <div className="text-sm text-muted-foreground mb-4">
        Короткое видео (2-5 минут) с демонстрацией работы системы
      </div>

      <div className="flex gap-2">
        <Badge variant="outline" className="text-xs">
          Обязательно
        </Badge>

        <Badge variant="outline" className="text-xs bg-red-600/10">
          Лаба 6
        </Badge>
      </div>
    </CardContent>
  </Card>

  <Card className="border-2 border-purple-600/30">
    <CardHeader>
      <div className="flex items-center gap-3">
        <div className="w-12 h-12 bg-purple-600 flex items-center justify-center">
          <FileText className="h-6 w-6 text-white" />
        </div>

        <CardTitle className="text-lg">
          Техническая документация
        </CardTitle>
      </div>
    </CardHeader>

    <CardContent>
      <div className="text-sm text-muted-foreground mb-4">
        API документация, архитектурные решения, deployment guide
      </div>

      <div className="flex gap-2">
        <Badge variant="outline" className="text-xs">
          Рекомендуется
        </Badge>

        <Badge variant="outline" className="text-xs bg-purple-600/10">
          Лаба 4-5
        </Badge>
      </div>
    </CardContent>
  </Card>
</div>

## Шаблоны и чек-листы [#шаблоны-и-чек-листы]

Мы подготовили готовые шаблоны для всех необходимых документов:

<div className="bg-muted/50 border-2 border-border p-6 my-8">
  <h3 className="text-lg font-bold mb-4 flex items-center gap-2">
    <Download className="h-5 w-5 text-purple-600" />

    Доступные шаблоны
  </h3>

  <div className="space-y-4">
    <div className="flex items-start gap-4 p-4 bg-background border border-border">
      <FileText className="h-6 w-6 text-blue-600 flex-shrink-0 mt-1" />

      <div className="flex-1">
        <div className="font-bold text-sm mb-1">
          README Template
        </div>

        <div className="text-xs text-muted-foreground mb-2">
          Полная структура README с разделами: описание, команда, архитектура, установка, метрики
        </div>

        <a href="/templates/PROJECT_README_TEMPLATE.md" target="_blank" className="text-xs text-purple-600 hover:text-purple-600 font-medium flex items-center gap-1">
          Открыть шаблон <ExternalLink className="h-3 w-3" />
        </a>
      </div>
    </div>

    <div className="flex items-start gap-4 p-4 bg-background border border-border">
      <CheckCircle2 className="h-6 w-6 text-green-600 flex-shrink-0 mt-1" />

      <div className="flex-1">
        <div className="font-bold text-sm mb-1">
          Demo Day Checklist
        </div>

        <div className="text-xs text-muted-foreground mb-2">
          Пошаговый чек-лист подготовки: презентация, видео, демо, таймлайн, критерии оценки
        </div>

        <a href="/templates/DEMO_DAY_CHECKLIST.md" target="_blank" className="text-xs text-purple-600 hover:text-purple-600 font-medium flex items-center gap-1">
          Открыть чек-лист <ExternalLink className="h-3 w-3" />
        </a>
      </div>
    </div>

    <div className="flex items-start gap-4 p-4 bg-background border border-border">
      <Github className="h-6 w-6 text-foreground/90 flex-shrink-0 mt-1" />

      <div className="flex-1">
        <div className="font-bold text-sm mb-1">
          Gallery Submission Guide
        </div>

        <div className="text-xs text-muted-foreground mb-2">
          Инструкция по публикации проекта в галерее на сайте курса после Demo Day
        </div>

        <a href="/templates/GALLERY_SUBMISSION_GUIDE.md" target="_blank" className="text-xs text-purple-600 hover:text-purple-600 font-medium flex items-center gap-1">
          Открыть инструкцию <ExternalLink className="h-3 w-3" />
        </a>
      </div>
    </div>
  </div>
</div>

## Требования к README.md [#требования-к-readmemd]

README должен содержать следующие **обязательные секции**:

### 1. Описание проекта [#1-описание-проекта]

* **Проблема**: Какую проблему решает проект (2-3 предложения)
* **Решение**: Как AI-система решает проблему
* **Целевая аудитория**: Кто будет использовать

### 2. Команда [#2-команда]

Таблица с информацией о каждом участнике:

| Роль                         | Участник      | Основные задачи                       |
| ---------------------------- | ------------- | ------------------------------------- |
| Product / Vision Owner       | Имя (@github) | Сегмент, гипотезы, use cases, скоуп   |
| AI Engineer                  | Имя (@github) | Промпты, RAG, качество ответов модели |
| Delivery Engineer            | Имя (@github) | Приложение, compose, CI/CD, прод      |
| AI Quality & Safety Engineer | Имя (@github) | Evals, регрессия, безопасность LLM    |

### 3. Архитектура [#3-архитектура]

* **Технологический стек**: LLM, VLM, RAG, Backend, Frontend, DevOps
* **Диаграмма системы**: C4 в PlantUML (`.puml` + `.svg` в репозитории)
* **Описание AI pipeline**: Как данные проходят через систему

### 4. Установка и запуск [#4-установка-и-запуск]

```bash
# Клонировать репозиторий
git clone https://github.com/your-org/project.git

# Настроить окружение
cp .env.example .env

# Запустить через Docker Compose
docker compose up -d
```

Обязательно указать:

* Требования (Docker версия, Node.js и т.д.)
* Порты на которых доступны сервисы
* Переменные окружения

### 5. Демо и результаты [#5-демо-и-результаты]

* **Скриншоты**: Минимум 3-4 основных экрана
* **Видео**: Ссылка на видео демонстрацию
* **Метрики**: Response time, token usage, test coverage

### 6. Документация [#6-документация]

Ссылки на:

* API Reference (Swagger/OpenAPI)
* Architecture Decision Records
* Deployment Guide

<Alert className="border-orange-600 bg-orange-600/10 mt-8">
  <AlertTriangle className="h-4 w-4 text-orange-600" />

  <AlertDescription className="text-orange-600">
    <strong>Важно:</strong> README пишется по ходу разработки, а не в последний момент. Обновляйте его после каждой лабораторной работы.
  </AlertDescription>
</Alert>

## Требования к презентации [#требования-к-презентации]

### Структура (10-12 слайдов, 10 минут) [#структура-10-12-слайдов-10-минут]

1. **Титульный слайд** — название, команда, дата
2. **Проблема** (Product/VO, 2 мин) — что решаем и почему важно
3. **Решение** (Product/VO + AI Engineer, 2 мин) — как AI решает проблему
4. **Технологии** (AI Engineer + Delivery, 1 мин) — стек и архитектура
5. **Демо** (Delivery, 3 мин) — показать работу системы
6. **Метрики и качество** (Quality + AI Engineer, 1 мин) — evals, наблюдаемость, результаты
7. **Уроки** (Product/VO, 1 мин) — что узнали, челленджи
8. **Roadmap** — что сделано, что планируется

### Распределение времени по ролям [#распределение-времени-по-ролям]

* **Product / Vision Owner**: 2-3 минуты (проблема, сегмент, итоги)
* **AI Engineer**: 2-3 минуты (промпты, RAG, что улучшало качество)
* **Delivery Engineer**: 2-3 минуты (прод, CI/CD, демо интерфейса)
* **AI Quality & Safety**: 2-3 минуты (evals, регрессия, безопасность)

### Требования к дизайну [#требования-к-дизайну]

* Читаемые шрифты (минимум 24pt)
* Контрастные цвета
* Больше визуалов, меньше текста
* Единый стиль
* Не читать текст со слайдов
* Не перегружать информацией

## Требования к видео демо [#требования-к-видео-демо]

### Что показать (2-5 минут) [#что-показать-2-5-минут]

1. **Вступление** (10 сек): название и команда
2. **Проблема** (20 сек): что решаем
3. **Демо интерфейса** (2-3 мин): основной user flow
4. **Behind the scenes** (30 сек): Langfuse, Grafana
5. **Заключение** (10 сек): призыв попробовать

### Технические требования [#технические-требования]

* **Разрешение**: минимум 1080p
* **Формат**: MP4 (H.264)
* **Звук**: качественный микрофон
* **Длительность**: 2-5 минут
* **Хостинг**: YouTube (unlisted) или Loom

## Чек-лист готовности к Demo Day [#чек-лист-готовности-к-demo-day]

<div className="bg-background border-2 border-purple-600 p-6 my-8">
  <h3 className="text-lg font-bold mb-4 text-purple-600">
    За 2 недели до Demo Day
  </h3>

  <div className="space-y-2 text-sm">
    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        README.md заполнен на 80%+
      </span>
    </div>

    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Начата работа над презентацией
      </span>
    </div>

    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Сделаны скриншоты интерфейса
      </span>
    </div>

    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Docker Compose работает стабильно
      </span>
    </div>
  </div>
</div>

<div className="bg-background border-2 border-green-600 p-6 my-8">
  <h3 className="text-lg font-bold mb-4 text-green-600">
    За 1 неделю до Demo Day
  </h3>

  <div className="space-y-2 text-sm">
    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Презентация готова (черновик)
      </span>
    </div>

    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Записано черновое видео
      </span>
    </div>

    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Собраны метрики из Grafana/Langfuse
      </span>
    </div>

    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Проведена первая репетиция
      </span>
    </div>
  </div>
</div>

<div className="bg-background border-2 border-red-600 p-6 my-8">
  <h3 className="text-lg font-bold mb-4 text-red-600">
    За 1 день до Demo Day
  </h3>

  <div className="space-y-2 text-sm">
    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Презентация финализирована (PDF)
      </span>
    </div>

    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Видео демо загружено
      </span>
    </div>

    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        README.md полностью заполнен
      </span>
    </div>

    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Live demo протестировано 3+ раза
      </span>
    </div>

    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Финальная репетиция с таймингом
      </span>
    </div>

    <div className="flex items-center gap-2">
      <input type="checkbox" className="h-4 w-4" />

      <span>
        Все ссылки рабочие
      </span>
    </div>
  </div>
</div>

## Критерии оценки документации [#критерии-оценки-документации]

Документация оценивается как часть общей оценки за проект:

<div className="grid grid-cols-1 md:grid-cols-3 gap-4 my-8">
  <Card className="border-green-600/30">
    <CardHeader>
      <CardTitle className="text-sm text-green-600">
        Отлично (90-100%)
      </CardTitle>
    </CardHeader>

    <CardContent className="text-xs text-muted-foreground">
      <ul className="space-y-1 list-disc list-inside">
        <li>
          Все секции README заполнены
        </li>

        <li>
          Качественные скриншоты и диаграммы
        </li>

        <li>
          Работающие инструкции по установке
        </li>

        <li>
          Профессиональная презентация
        </li>

        <li>
          Отличное видео демо
        </li>
      </ul>
    </CardContent>
  </Card>

  <Card className="border-yellow-600/30">
    <CardHeader>
      <CardTitle className="text-sm text-yellow-600">
        Хорошо (70-89%)
      </CardTitle>
    </CardHeader>

    <CardContent className="text-xs text-muted-foreground">
      <ul className="space-y-1 list-disc list-inside">
        <li>
          Основные секции заполнены
        </li>

        <li>
          Есть скриншоты
        </li>

        <li>
          Инструкции работают
        </li>

        <li>
          Хорошая презентация
        </li>

        <li>
          Базовое видео
        </li>
      </ul>
    </CardContent>
  </Card>

  <Card className="border-red-600/30">
    <CardHeader>
      <CardTitle className="text-sm text-red-600">
        Неудовлетворительно (<70%)
      </CardTitle>
    </CardHeader>

    <CardContent className="text-xs text-muted-foreground">
      <ul className="space-y-1 list-disc list-inside">
        <li>
          README неполный
        </li>

        <li>
          Нет скриншотов
        </li>

        <li>
          Инструкции не работают
        </li>

        <li>
          Слабая презентация
        </li>

        <li>
          Нет видео
        </li>
      </ul>
    </CardContent>
  </Card>
</div>

## Полезные ссылки [#полезные-ссылки]

<div className="grid grid-cols-1 md:grid-cols-2 gap-4 my-8">
  <div className="border-2 border-border p-4">
    <h4 className="font-bold text-sm mb-2 flex items-center gap-2">
      <FileText className="h-4 w-4 text-blue-600" />

      Примеры хороших README
    </h4>

    <ul className="text-xs space-y-1 text-muted-foreground">
      <li>
        • 

        <a href="https://github.com/tiangolo/fastapi" className="text-purple-600 hover:underline">FastAPI</a>

         — отличная структура
      </li>

      <li>
        • 

        <a href="https://github.com/langchain-ai/langchain" className="text-purple-600 hover:underline">LangChain</a>

         — технический README
      </li>

      <li>
        • 

        <a href="https://github.com/excalidraw/excalidraw" className="text-purple-600 hover:underline">Excalidraw</a>

         — много визуалов
      </li>
    </ul>
  </div>

  <div className="border-2 border-border p-4">
    <h4 className="font-bold text-sm mb-2 flex items-center gap-2">
      <Presentation className="h-4 w-4 text-green-600" />

      Инструменты для презентаций
    </h4>

    <ul className="text-xs space-y-1 text-muted-foreground">
      <li>
        • 

        <a href="https://pitch.com" className="text-purple-600 hover:underline">Pitch.com</a>

         — современные презентации
      </li>

      <li>
        • 

        <a href="https://canva.com" className="text-purple-600 hover:underline">Canva</a>

         — простой дизайн
      </li>

      <li>
        • 

        <a href="https://excalidraw.com" className="text-purple-600 hover:underline">Excalidraw</a>

         — диаграммы
      </li>
    </ul>
  </div>

  <div className="border-2 border-border p-4">
    <h4 className="font-bold text-sm mb-2 flex items-center gap-2">
      <Video className="h-4 w-4 text-red-600" />

      Инструменты для видео
    </h4>

    <ul className="text-xs space-y-1 text-muted-foreground">
      <li>
        • 

        <a href="https://obsproject.com" className="text-purple-600 hover:underline">OBS Studio</a>

         — запись экрана
      </li>

      <li>
        • 

        <a href="https://loom.com" className="text-purple-600 hover:underline">Loom</a>

         — быстрая запись
      </li>

      <li>
        • 

        <a href="https://www.blackmagicdesign.com/products/davinciresolve" className="text-purple-600 hover:underline">DaVinci Resolve</a>

         — монтаж
      </li>
    </ul>
  </div>

  <div className="border-2 border-border p-4">
    <h4 className="font-bold text-sm mb-2 flex items-center gap-2">
      <Github className="h-4 w-4 text-foreground/90" />

      Шаблоны на GitHub
    </h4>

    <ul className="text-xs space-y-1 text-muted-foreground">
      <li>
        • 

        <a href="/templates/PROJECT_README_TEMPLATE.md" className="text-purple-600 hover:underline">README Template</a>
      </li>

      <li>
        • 

        <a href="/templates/DEMO_DAY_CHECKLIST.md" className="text-purple-600 hover:underline">Demo Day Checklist</a>
      </li>

      <li>
        • 

        <a href="/templates/GALLERY_SUBMISSION_GUIDE.md" className="text-purple-600 hover:underline">Gallery Guide</a>
      </li>
    </ul>
  </div>
</div>

<Alert className="border-blue-600 bg-blue-600/10 mt-8">
  <CheckCircle2 className="h-4 w-4 text-blue-600" />

  <AlertDescription className="text-blue-600">
    Помните: качественная документация — это инвестиция в ваше портфолио. Работодатели оценивают не только код, но и способность его объяснить.
  </AlertDescription>
</Alert>