ТЗ · API · Инструкции · Регламенты
Техническаядокументация
Документация, по которой решение можно разрабатывать, внедрять и сопровождать
Когда знания о системе существуют только в головах разработчиков, проект зависит от конкретных людей: их уход обнуляет экспертизу, а подключение новой команды занимает месяцы. Мы разрабатываем техническую документацию полного цикла: ТЗ, спецификации, описания API, пользовательские инструкции и регламенты эксплуатации.
Полнота комплекта
ТЗ, спецификации, описания API, инструкции и регламенты поддержки — единым согласованным пакетом
Понятность для каждой роли
Документы написаны для своей аудитории: разработчиков, интеграторов, пользователей, поддержки
Независимость от людей
Знания зафиксированы документально: сопровождение может вести любая квалифицированная команда
- ГОСТ 19/34
- OpenAPI
- Docs as Code
- Confluence
- GitBook
- Swagger
- Markdown
- Скринкасты
Об услуге
Документация — это интерфейс для людей
Техническая документация — это всё, что объясняет систему людям: ТЗ для заказа разработки, спецификации для команды, описание API для интеграторов, инструкции для пользователей, регламенты для эксплуатации. Хорошая документация отвечает на вопросы до того, как их задали.
Мы пишем документы как продукт: с читателем в голове, примерами из реальности и структурой, в которой находят нужное за минуту. И настраиваем процесс: документация обновляется вместе с релизами, а не «когда-нибудь потом». От одной инструкции до полного комплекта по ГОСТ — под вашу задачу.
Код говорит «как», документация — «почему» и «что делать». Без неё система принадлежит тем, кто её помнит.
Задачи услуги
Какие задачи решает документация
Заказать и принять разработку
ТЗ и спецификации: объём работ зафиксирован, приёмка объективна, споры исключены.
Подключать интеграторов без боли
Описание API с примерами: партнёры интегрируются сами, не отвлекая вашу команду.
Ускорить онбординг сотрудников
Инструкции и база знаний: новый человек работает самостоятельно через неделю.
Разгрузить поддержку
Пользовательские инструкции и FAQ: типовые вопросы закрываются без обращений.
Обеспечить эксплуатацию
Регламенты поддержки: кто, что и в какие сроки делает при инцидентах и обновлениях.
Пройти аудит и сертификацию
Комплект документов по ГОСТ и отраслевым требованиям: для тендеров, проверок, договоров.
Состав услуги
Что входит в услугу
- Пишем технические задания: по ГОСТ 34/19 или в адаптированном формате
- Готовим функциональные спецификации: сценарии, правила, состояния интерфейсов
- Описываем нефункциональные требования: производительность, надёжность, ИБ
- Оформляем для договора: объём обязательств зафиксирован юридически
- Документы, по которым можно строить, сметить и принимать
Артефакт: ТЗ, ЧТЗ, спецификации требований
- Описываем API в OpenAPI: endpoints, схемы данных, коды ошибок, авторизация
- Пишем примеры запросов и ответов: на реальных сценариях, не «foo-bar»
- Готовим гайды по интеграции: с чего начать, типовые сценарии, ограничения
- Собираем портал разработчика: Swagger UI, GitBook или ваш формат
- Интеграторы подключаются самостоятельно: ваша команда разгружена
Артефакт: OpenAPI-спецификация + портал
- Пишем инструкции для каждой роли: администратор, оператор, конечный пользователь
- Структура от задач: «как сделать X», а не «кнопки интерфейса по порядку»
- Иллюстрируем скриншотами и схемами: каждый шаг виден
- Собираем базу знаний: поиск, разделы, типовые проблемы и решения
- Пишем языком пользователя: проверяем на реальных людях
Артефакт: Руководства пользователя + база знаний
- Описываем регламенты эксплуатации: мониторинг, бэкапы, обновления, окна работ
- Фиксируем порядок реагирования на инциденты: эскалация, SLA, роли
- Готовим инструкции по развёртыванию и обновлению: пошагово, с откатом
- Описываем регламенты поддержки пользователей: приём, классификация, сроки
- Эксплуатация становится процессом, а не искусством отдельных людей
Артефакт: Комплект эксплуатационных регламентов
- Аудируем существующую документацию: что актуально, что устарело, чего нет
- Восстанавливаем описание системы по коду и интервью с командой
- Приводим комплект к единой структуре и стилю
- Закрываем критичные пробелы: архитектура, интеграции, данные
- Система снова принадлежит компании, а не памяти отдельных людей
Артефакт: Актуальный комплект по существующей системе
- Внедряем docs as code: документация в репозитории, ревью, версии вместе с кодом
- Настраиваем процесс: кто и когда обновляет документы при релизе
- Определяем владельцев разделов: ответственность закреплена
- Ведём документацию на аутсорсе: наш техписатель в вашем контуре
- Документы перестают устаревать: актуальность — часть процесса разработки
Артефакт: Docs as Code + регламент обновления
Актуальность
Чем грозит жизнь без документации
Уход ключевого человека — катастрофа
Единственный, кто понимает интеграцию, уволился. Восстановление знаний по коду и логам — недели работы и риск ошибок в проде.
Поддержка тонет в одинаковых вопросах
«Как сбросить пароль» — 30% обращений. Без инструкций и базы знаний каждый пользователь звонит, а команда поддержки растёт вместе с продажами.
Каждый интегратор отвлекает вашу команду
Партнёр хочет подключиться — и начинаются недели вопросов вашим разработчикам. Без описания API каждая интеграция стоит вам дороже, чем партнёру.
Инцидент в пятницу вечером
Система упала, дежурный не знает, что делать, регламента нет. Восстановление занимает часы вместо минут — и уходит в выходные.
Система без документации принадлежит не компании, а тем, кто её помнит. Люди меняются — документы остаются. Если их нет, не остаётся ничего.
Результат
Что вы получаете на выходе
ТЗ и спецификации
Документы для заказа и приёмки разработки: по ГОСТ или в адаптированном формате.
OpenAPI-спецификация
Полное описание API: endpoints, схемы, ошибки, примеры. Портал разработчика опционально.
Руководства пользователя
Инструкции по ролям со скриншотами: от задачи к решению, языком пользователя.
База знаний
Структурированный портал с поиском: инструкции, FAQ, типовые проблемы и решения.
Эксплуатационные регламенты
Мониторинг, обновления, инциденты, бэкапы: кто, что и в какие сроки.
Процесс обновления
Docs as code или регламент ведения: документация остаётся актуальной после нас.
Всё, что мы делаем, остаётся вашим: код, документация, процессы. Поддерживать и развивать решение можете вы сами, наша команда или любой другой подрядчик.
Форматы работы
Сколько это стоит
Цена зависит от типа и объёма документов: инструкция на один процесс и полный комплект по ГОСТ — разные задачи. Начать можно с аудита: поймёте, что есть, чего не хватает и что делать в первую очередь. Ниже — типовые форматы работы.
Быстрый старт
Аудит документации
- Инвентаризация существующих документов
- Оценка актуальности и полноты
- Карта пробелов: чего не хватает
- Приоритеты: что критично закрыть
- Рекомендации по структуре комплекта
- План работ с оценкой трудоёмкости
Типовые форматы
Пакет документов
Один тип документов под вашу задачу: инструкции, API или регламенты
- Руководства пользователя по ролям
- Или описание API с примерами
- Или комплект регламентов эксплуатации
- Единая структура и стиль
- Передача в редактируемом виде
Полный комплект под ключ
Вся документация продукта: ТЗ, API, инструкции, регламенты, база знаний
- ТЗ и спецификации
- OpenAPI + портал разработчика
- Руководства пользователя и база знаний
- Регламенты эксплуатации и поддержки
- Процесс обновления документации
Технический писатель в команду
Выделенный техписатель на поток документов
- Новые документы по мере развития продукта
- Актуализация существующего комплекта
- Ведение базы знаний
- Docs as code в вашем контуре
Цены выше — ориентир, а не коммерческое предложение. Точную смету называем после предпроектного обследования — и фиксируем в договоре.
Кейсы
Проекты, где документация играли большое значение
Этапы
Как мы работаем
Разработка документации — это от 2 недель для аудита до 3–4 месяцев для полного комплекта. Работаем рядом с вашей командой: изучаем систему, пишем, проверяем на пользователях. Расскажите о вашей задаче?
Обсудить проектПогружение
Изучаем систему, аудируем существующие документы, определяем читателей и их задачи.
Структура
Проектируем комплект: состав документов, структура каждого, стиль и форматы.
Написание
Пишем документы итерациями: черновик, ревью с вашей командой, уточнение.
Проверка
Тестируем на реальных читателях: находят ли нужное, понимают ли, хватает ли деталей.
Передача и процесс
Передаём комплект в редактируемом виде, настраиваем процесс обновления, обучаем команду.
Команда
Кто будет работать над проектом
Единая точка входа: сроки, организация доступов и ревью, отчётность.
Архитектура комплекта и стандарты: структура, стиль, качество каждого документа.
Пишут документы: изучают систему, интервьюируют команду, готовят тексты и иллюстрации.
Отвечает за техническую точность: API, интеграции, архитектура, данные.
Проверяет язык и единообразие: документы читаются легко и выглядят цельно.
На типовом проекте работают ведущий техписатель и 1–2 писателя, аналитик подключается на технические разделы. Все специалисты в штате, без субподряда.
О компании
Articul — digital-агентство полного цикла
лет опыта в цифровой разработке
реализованных проектов
клиентов
специалистов в команде
наград и премий
Клиенты
Нам доверяют
350 клиентов уже доверили нам свои проекты: спортивные лиги, федеральный ритейл, фарма и промышленность
FAQ
Частые вопросы
Могут — но обычно не пишут, потому что их наняли разрабатывать. И пишут для себя: документ разработчика не понимает пользователь. Техписатель переводит с технического на человеческий и делает это профессией, а не «в свободное время».
Читаем код и схемы, работаем в тестовом контуре, интервьюируем команду. Плюс задаём «глупые» вопросы — именно они выявляют то, что очевидно вам и непонятно читателю. Наш рекорд погружения в новую систему — одна неделя до первого документа.
Если требуют тендер, заказчик или регулятор — да, сделаем по ГОСТ 19/34 с нужными формами. Если нет — рекомендуем современные форматы: они живее, дешевле в поддержке и удобнее читателю. Подскажем, что подойдёт вашей ситуации.
Поэтому мы не просто пишем, а настраиваем процесс: владельцы разделов, обновление при релизах, docs as code в репозитории. Можем вести документацию на аутсорсе — тогда актуальность наша ответственность, а не ваша надежда.
Частично — и мы это делаем: справочники API генерируются из аннотаций и OpenAPI, схемы данных — из моделей. Но сценарии, примеры и объяснения «почему так» генерируются плохо: их пишет человек. Правильный ответ — связка автогенерации и авторского текста.
На рынке аутстафф техписателей — от 2 100 ₽/час. Но мы продаём результат, а не часы: пакет документов с фиксированной сметой. Так вы платите за готовый комплект, а не за процесс его написания.