Ответ
На проекте документация охватывает разные аспекты и аудитории:
- Техническое задание / Требования (SRS, PRD): Описание бизнес-целей, функциональных и нефункциональных требований к системе.
- Техническая документация (Technical Design, API Docs):
- Дизайн-документы: Архитектура, схемы баз данных, алгоритмы.
- API-документация (Swagger/OpenAPI): Описание эндпоинтов, методов, запросов и ответов.
- Документация по тестированию: Тест-план, тест-кейсы, чек-листы, баг-репорты.
- Пользовательская документация: Руководство пользователя, справочная система, релиз-ноты.
- Процессная документация: Описание рабочих процессов (например, процедура code review, процесс деплоя).
Пример структуры API-документации в Swagger (YAML):
paths:
/api/v1/login:
post:
summary: User authentication
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
example: "user@example.com"
password:
type: string
example: "mySecretPass123"
responses:
'200':
description: Successfully authenticatedКаждый вид документации служит своей цели: требования задают «что» делать, техническая документация — «как», а тестовая — «как проверить».
Ответ 18+ 🔞
Да ты посмотри, какая тут, блядь, бумажная волокита развелась! Проект, а документов — овердохуища, и каждая — со своим приколом, будто в цирке.
Вот смотри, с чего всё начинается, перед тем как кодить. Это типа «Техническое задание» или там «Требования». Там сидят дядьки в пиджаках и пишут, блядь, что система должна делать, а чего не должна. Типа «хочу кнопку, чтобы она была красная и при нажатии раздавался звук „буп“». Это святое, без этого нихуя не стронутся.
А потом уже наши, технари, берут это и делают «Техническую документацию». Это уже наше, родное. Там мы расписываем, как эту красную кнопку, сука, будем делать. Какая у неё там архитектура, как она с базой данных общается, какие алгоритмы внутри. И самое главное — API-документация. Без неё фронтендеры тебе мозг вынесут вопросами «а как мне залогиниться-то?».
Вот, смотри, как это примерно выглядит, чтоб ты понимал масштаб пиздеца:
paths:
/api/v1/login:
post:
summary: User authentication
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
example: "user@example.com"
password:
type: string
example: "mySecretPass123"
responses:
'200':
description: Successfully authenticatedВидишь? Всё чётко: куда стучаться, что в тело запроса сувать, и что в ответе ждать. Красота, ёпта!
Но это ещё не всё! Пока мы тут кнопку пилим, другие ребята — тестировщики — уже готовят «Документацию по тестированию». Они придумывают, как эту кнопку сломать. Пишут тест-кейсы: «нажать один раз — ок, нажать сто раз подряд — система не должна упасть». Герои, блядь, без них мы бы давно в пролёте были.
А когда всё готово и работает, появляется «Пользовательская документация». Это для тех, кто, прости господи, будет этой штукой пользоваться. Руководства, справки, релиз-ноты типа «в версии 2.0 кнопка стала не только красной, но и мигающей, вы довольны?».
Ну и куда же без бюрократии — «Процессная документация». Тут уже описывают, как правильно мержить код, как его деплоить, кто за что отвечает. Чтоб не было, что один чувак всё задеплоил, а остальные офигели.
Короче, суть в чём: требования говорят «что» делать, техничка — «как», а тесты — «как проверить». Всё на своих местах, как кирпичи в стене. А иначе — пиздец и хаос, и проект накрывается медным тазом.