Запуск продукта
Техническая документация
Описание системы, по которому её можно передать другой команде: архитектура, эндпоинты, окружения и порядок выкладки.
- Ответ на заявку
- в течение 24 часов
- Первый звонок
- 30 минут, без обязательств
- Первая рабочая версия
- через 3 недели
Процесс
Что происходит и когда
Работа разбита на этапы, у каждого назван результат. Вы видите его сами, а не узнаёте о нём из отчёта.
Дни 1–5
Опись знаний
Смотрим, кому документация нужна и зачем: ввести нового разработчика, передать систему другой команде или пройти проверку заказчика — это три разных документа. Составляем опись: что уже описано, что живёт только в коде и что знает один человек и больше никто.
На выходе — Опись знаний и назначение документа
Недели 2–3
Схема системы
Описываем систему: из каких сервисов состоит, кто с кем разговаривает, где лежат данные и что происходит при отказе каждого куска. Схемы рисуются по коду и конфигурации, а не по рассказу: расхождения между тем, как задумано, и тем, как работает, находятся именно здесь и выписываются отдельным списком.
На выходе — Схема по коду и список расхождений
Недели 3–4
Эндпоинты и окружения
Эндпоинты и окружения: запрос, ответ, коды ошибок, переменные окружения и то, чем тестовое отличается от боевого. Каждый пример вызывается руками — то, что не воспроизвелось, в документ не попадает, даже если в коде написано иначе.
На выходе — Описание эндпоинтов с проверенными примерами
Перед передачей
Порядок выкладки
Порядок выкладки: как собрать, как выкатить, что проверить после и как откатить, если пошло не так. Документ проверяется чужими руками — по нему поднимают окружение с нуля, и каждое место, где человек застрял, дописывается.
На выходе — Инструкция выкладки, проверенная чужими руками
Когда система меняется
Документ рядом с кодом
Документация устаревает с первым же релизом. Поэтому она лежит рядом с кодом, в том же репозитории, и правится той же задачей, что и код; если держать её актуальной некому, обновление можно отдать нам пакетом часов.
На выходе — Документация в репозитории, живущая вместе с кодом
Что входит в работу
Опись знаний
что уже описано, что живёт только в коде, а что знает один человек и больше никто
Схема системы
сервисы, кто с кем разговаривает, где лежат данные и что происходит при отказе каждого куска; рисуется по коду, а не по рассказу
Расхождения с задуманным
отдельный список мест, где система работает не так, как о ней рассказывают, — их находит сверка схемы с кодом
Описание эндпоинтов
запрос, ответ, коды ошибок и примеры вызовов; каждый пример вызван руками, невоспроизведённое в документ не идёт
Окружения и выкладка
какие переменные нужны, чем тестовое отличается от боевого, как собрать, выкатить, что проверить и как откатить
Markdown рядом с кодом
документ лежит в вашем репозитории и правится той же задачей, что и код; схемы — исходниками, описание API — в OpenAPI
Что нужно от вас
- Ваше решение, кому документ адресован — новому разработчику, принимающей команде или проверке заказчика
- Два-три разговора по часу с разработчиками на каждый кусок системы — из кода не видно, почему выбрано именно это
- Тестовое окружение с рабочими ключами, чтобы каждый пример из документа был вызван руками
Что обычно спрашивают
Контакты
Пришлите описание задачи
Ответ с объёмом работ, сроками и оценкой бюджета придёт в течение 24 часов.
Первый звонок — 30 минут, без обязательств с вашей стороны.
01
Вы описываете задачу
Пять вопросов в форме или письмо в свободной форме — как удобнее.
02
Мы отвечаем за сутки
С объёмом работ, сроками и оценкой бюджета — по тому, что вы рассказали.
03
Созваниваемся на 30 минут
Уточняем непонятное. Ни к чему вас не обязывает.