Модуль 04 — README и документация проекта

README отвечает на вопросы человека, который впервые открыл репозиторий: что это, зачем, как запустить и к кому обращаться. Хороший README позволяет развернуть проект, ни разу не спросив автора.

# Портал заданий

Сервис приёма и проверки учебных работ для курсов Nevabit.

## Возможности

- сдача работ текстом и файлами
- проверка по критериям с комментариями
- журнал оценок по группам

## Требования

- Debian 13
- PostgreSQL 17
- PHP 8.4

## Установка

1. Склонируйте репозиторий
1. Скопируйте `config.example.php` в `config.php` и укажите доступ к базе
1. Выполните установку:

   ```bash
   php admin/cli/install_database.php
   ```

## Использование

Краткий пример основного сценария или ссылка на [руководство](docs/usage.md).

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

- [Установка на сервер](docs/install.md)
- [Частые вопросы](docs/faq.md)
- [История изменений](CHANGELOG.md)

## Контакты

Вопросы и ошибки — в задачи репозитория.

project/
├── README.md          что это и как запустить
├── CHANGELOG.md       история изменений по версиям
├── CONTRIBUTING.md    как предлагать изменения
└── docs/
    ├── install.md     установка на сервер
    ├── usage.md       руководство пользователя
    ├── faq.md         частые вопросы
    └── img/           изображения для документации

Журнал изменений удобно вести по соглашению Keep a Changelog: новые версии сверху, изменения сгруппированы по типу, для ещё не выпущенных изменений есть раздел Unreleased.

# Changelog

## [Unreleased]

### Added
- Выгрузка ведомости в Excel

## [1.1.0] - 2026-09-20

### Added
- Оценочные листы для заданий курса «Базы данных»

### Fixed
- Сброс нумерации в инструкции по установке

## [1.0.0] - 2026-09-13

### Added
- Первая версия портала

Markdown прощает многое: неаккуратный документ всё равно как-то отобразится. Чтобы документация команды выглядела одинаково и не ломалась на другой платформе, стиль проверяют линтером — markdownlint. В VS Code он ставится расширением и подчёркивает нарушения прямо при наборе.

Правила, которые команде не подходят, отключают в файле .markdownlint.json в корне проекта — например, ограничение длины строки MD013 для русских текстов часто выключают:

{
  "MD013": false
}

Не всем удобно читать документацию в репозитории: заказчику или учебной части нужен файл Word. Для этого есть Pandoc — конвертер между форматами, устанавливается из репозитория пакетов системы (в Debian: apt install pandoc).

# Markdown → Word
pandoc README.md -o README.docx

# Markdown → самостоятельная HTML-страница
pandoc -s docs/install.md -o install.html

# Несколько файлов в один документ
pandoc README.md docs/install.md docs/usage.md -o manual.docx