PHPTime

13 ошибок в документации, которые отталкивают пользователей вашего проекта

Документация решает, станет ли ваш пакет инструментом, который советуют коллегам, или репозиторием, который закрывают через пять минут после звёздочки. Большинство провалов связано не с отсутствием текста, а с тем, что он написан без учёта реального сценария читателя. Разберём ошибки, которые чаще всего встречаются в PHP-проектах, и способы их исправить.

1. README не отвечает на главные вопросы за минуту

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

  • какую задачу решает пакет;
  • подходит ли он под его окружение;
  • какие зависимости нужны;
  • сколько усилий займёт установка и первый запуск.

Если ответы спрятаны в глубине wiki или в мыслях автора — README не работает. Для PHP-пакета обязательно укажите минимальную поддерживаемую версию языка и расширения. Не «требуется PHP 8», а конкретно: PHP 8.3+, ext-json, ext-pdo_mysql. Это сразу отсекает тех, у кого окружение не подходит, и экономит время остальным.

PHP
// composer.json — зависимости должны быть явными
{
    "require": {
        "php": "^8.3",
        "ext-pdo": "*"
    },
    "suggest": {
        "ext-redis": "Нужно для кэширования результатов"
    }
}

2. Термины без контекста

Автору кажется, что «адаптер репозитория», «нормализация DTO» или «Value Object» понятны по умолчанию. Читатель, который пришёл из другой команды или работает с соседним стеком, теряет нить на первом же абзаце. Любой специфичный термин при первом появлении нужно объяснять одной фразой или ссылкой на подробный материал.

Особенно это касается доменных понятий. Если пакет считает «коэффициент удержания клиента», определение должно быть не в коде, а в документации: что входит в формулу, какие периоды учитываются, где границы применимости.

3. Сравнение с аналогами вместо описания возможностей

Фраза «это как Doctrine, но легче и быстрее» не несёт информации тому, кто Doctrine не использовал. Сравнение оправдано только в таблице миграции: «в нашем API метод называется persist(), в Doctrine — persist(), но поведение отличается так-то». В остальных случаях описывайте функциональность напрямую: что делает, какие входные данные принимает, какие ограничения имеет.

4. Онлайн-документация недоступна офлайн

Многие разработчики читают документацию в моменты, когда интернета нет: в транспорте, в изолированном контуре, во время переезда серверов. Если ваш пакет устанавливается через Composer, документация должна быть доступна локально. Простой вариант — Markdown-файлы в каталоге docs/ внутри пакета. Более продвинутый — генерация HTML из тех же Markdown-файлов.

Не заставляйте пользователя искать единственную актуальную страницу на сайте. Если у вас есть и сайт, и файлы в репозитории, определите, какой источник считается каноническим. Раздвоение источника правды приводит к устаревшим инструкциям.

5. Примеры без реальных данных

Абстрактные $foo, $bar и lorem ipsum показывают синтаксис, но не учат применять пакет. Читателю нужно видеть, как выглядит вызов в контексте задачи.

Плохо:

PHP
$result = $parser->parse($input, $options);

Хорошо:

PHP
// Разбираем CSV-выгрузку заказов
$csv = \"id;customer;total\\n1001;ООО «Ромашка»;12500.50\\n\";

$parser = new CsvParser(
    delimiter: ';',
    skipEmptyLines: true,
);

$result = $parser->parse(
    input: $csv,
    options: new ParseOptions(
        header: true,
        strictTypes: true,
    ),
);

// $result содержит коллекцию объектов OrderRow

Пример с конкретными значениями отвечает на вопрос «как это применить у меня?». Читатель подставляет свои данные по образцу.

6. Фрагменты кода нельзя скопировать и запустить

Главный источник раздражения в PHP-документации — сниппеты, которые не работают после копирования. Причины типичны: нет объявления класса, пропущен импорт, не хватает параметра, используется несуществующий метод. В версии 8.3–8.5 добавьте строгую типизацию и явные типы параметров, чтобы примеры соответствовали современному стилю.

PHP
declare(strict_types=1);

use App\Formatter\InvoiceFormatter;

// Полный рабочий пример: можно сохранить в файл и выполнить
$formatter = new InvoiceFormatter(
    locale: 'ru_RU',
    decimalSeparator: ',',
);

/** @var array{id: int, total: float} $rawInvoice */
$rawInvoice = ['id' => 3547, 'total' => 18990.00];

$output = $formatter->render($rawInvoice);

echo $output;

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

7. Документация не учитывает путь новичка

Разработчик, который написал пакет, слишком глубоко внутри архитектуры. Он не помнит, что знал о проекте две недели назад. Поэтому вводная часть должна быть отдельным разделом, а не побочным замечанием в API-справочнике.

Хорошая структура для PHP-пакета:

  1. Установка — команда composer, проверка окружения.
  2. Быстрый старт — 10–15 строк кода, дающих первый результат.
  3. Основные сценарии — типовые задачи с примерами.
  4. Справочник API — детальное описание классов и методов.
  5. Обработка ошибок и ограничения — особенности поведения.

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

8. Документация по API без описания побочных эффектов

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

PHP
/**
 * Находит записи по фильтру.
 *
 * ВНИМАНИЕ: если передан параметр $withTrashed = true,
 * метод изменяет внутренний флаг запроса.
 *
 * @throws InvalidFilterException если фильтр содержит
 *         несуществующие поля
 */
public function findBy(
    Filter $filter,
    bool $withTrashed = false,
): Collection {
    // ...
}

Документируйте не только счастливый путь, но и граничные случаи. Что произойдёт, если передать пустую строку, ноль, null, отрицательное число? Для PHP 8.3–8.5 с строгой типизацией многие ошибки уходят на уровень TypeError, но поведение всё равно нужно описывать.

9. Отсутствие примеров обработки ошибок

Документация часто показывает идеальный запуск и обрывается. Реальный пользователь первым делом сталкивается с ошибкой: неверный формат данных, таймаут внешнего сервиса, конфликт версий. Покажите, как поймать исключение, как отличить один тип ошибки от другого, как писать логи.

PHP
use App\Exception\ValidationException;
use App\Exception\ServiceUnavailableException;

try {
    $report = $reportService->generate($period);
} catch (ValidationException $e) {
    // Данные периода некорректны — показываем форму с ошибкой
    $errors = $e->getErrors();
} catch (ServiceUnavailableException $e) {
    // Внешний API недоступен — пробуем кэш или откладываем задачу
    $this->queue->push($period);
}

Блок обработки ошибок перед примерами основной логики экономит пользователю часы отладки.

10. Нет информации об ограничениях и производительности

Когда пакет начинает работать медленно на больших объёмах, пользователь решает, что код плохой. Хотя проблема могла быть задокументирована. Указывайте:

  • на каких объёмах данных тестировался пакет;
  • какие операции ресурсоёмкие;
  • где нужны кэш или порционная обработка;
  • какие расширения PHP дают прирост производительности.

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

PHP
// Для больших выборок используйте генератор:
// память не растёт пропорционально количеству строк
public function iterateRows(): \Generator {
    $stmt = $this->pdo->query('SELECT id, data FROM logs');

    while ($row = $stmt->fetch(PDO::FETCH_ASSOC)) {
        yield $row;
    }
}

11. Примеры не обновляются под новые версии PHP

Документация на PHP 5.6 с mysql_* — это не просто устаревший текст, это вредный совет. Поддерживаемые версии PHP в конце 2026 года — 8.3, 8.4, 8.5. Все примеры должны работать на них.

Устаревший подходАктуальная замена
mysql_query()PDO или mysqli
ereg()preg_match()
create_function()анонимные функции
массивы без типовdeclare(strict_types=1), DTO, enum
each()foreach или array_key_first()

Если в документации встречается устаревший код, пометьте его: «так было принято в PHP 5, сейчас так не пишите». В противном случае новичок скопирует антиквариат.

12. Нет канала обратной связи

Документация без обратной связи умирает. Пользователь находит ошибку, хочет её исправить, но не понимает куда писать. В README и в финальном разделе документации укажите:

  • куда отправлять баг-репорты;
  • как предлагать правки к документации;
  • в каком формате описывать проблему: версия PHP, окружение, воспроизводимый пример.

Обратная связь должна вести к изменениям. Если пользователь тратит время на подробный репорт, а issue закрывается ботом без ответа — второй раз он не придёт.

13. Документация и код расходятся

Это самая тихая катастрофа. Код обновился: метод переименовался, параметр стал обязательным, появился enum вместо строки. А документация осталась прежней. Пользователь копирует пример, получает ошибку и делает вывод, что пакет сломан.

Боритесь с расхождением системно:

  • примеры в документации должны запускаться в CI;
  • при изменении сигнатур методов обновляйте DocBlock до выпуска релиза;
  • если проект большой, используйте генерацию API-справочника из кода;
  • в changelog явно указывайте, какие части документации затронуты.

Документация — это тоже код. Она требует ревью, тестирования и регулярного обновления.

Практический чек-лист

  1. README отвечает на вопросы «что это», «для кого», «как установить» за первую минуту.
  2. Термины объяснены при первом появлении.
  3. Примеры используют реальные данные и полный рабочий код.
  4. Для каждого сниппета указаны предварительные требования.
  5. Документация доступна офлайн в составе пакета.
  6. Есть отдельный быстрый старт для новичков.
  7. Обработка ошибок показана явно.
  8. Ограничения производительности описаны.
  9. Примеры актуальны для PHP 8.3–8.5 со строгой типизацией.
  10. Указан канал связи с авторами.

Частые вопросы

С чего начать писать документацию для PHP-пакета?

Начните с README: название, задача, минимальная версия PHP, установка через Composer, один рабочий пример из 10–15 строк. Затем добавьте быстрый старт и описание типовых сценариев. API-справочник можно генерировать из DocBlock.

Как поддерживать документацию в актуальном состоянии?

Запускайте примеры кода в CI, обновляйте DocBlock одновременно с изменением сигнатур, проверяйте актуальность сниппетов перед каждым релизом. В changelog указывайте, какие части документации затронуты.

Обязательно ли добавлять declare(strict_types=1) в примеры?

Если вы ориентируетесь на PHP 8.3 и новее, добавляйте. Это соответствует современному стилю и защищает читателя от неожиданных приведений типов. Если ваш пакет совместим только с более старыми версиями — явно укажите это.

Справка по теме

Ещё в разделе «Архитектура и практика»

Инверсия управления в PHP: Голливудский принцип

Разбираем принцип инверсии управления (IoC) в современном PHP: отличие от DI, события и наблюдатели, примеры на PHP 8.3–8.5, антипаттерны и чек-лист внедрения.

8 мин

Эффективный рефакторинг PHP-кода

Практическое руководство по рефакторингу в PHP 8.3–8.5. Как зафиксировать поведение тестами, усилить типизацию, разделить обязанности и удалить мёртвый код.

7 мин

Декаплинг и фреймворки в PHP: как перестать зависеть от чужих обновлений

Как отделить бизнес-логику от фреймворка в современных PHP-проектах. Интерфейсы, DTO, адаптеры, DI-контейнеры и стратегии миграции без остановки разработки.

7 мин

Как задать вопрос по PHP, чтобы получить ответ

Как задать вопрос по PHP: соберите минимальный воспроизводимый пример, укажите версии и условия запуска, приложите текст ошибки и выберите площадку.

7 мин