Перейти к содержанию
Документация

Документация, которой кто-то поверит

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

Что сюда входит

Документы, которые стоит иметь

Архитектура

Из чего состоит система и как связаны части, на уровне детальности, который переживёт ближайшие три месяца.

Инфраструктура и выкладка

Где работает, как изменение доезжает до production и что делать, когда это ломается в два часа ночи.

Решения и обоснования

Почему выбрано именно это. Та часть, которая всегда теряется и всегда нужна потом.

Онбординг

Что новому разработчику или новому агенту надо знать, прежде чем к чему-то прикасаться.

Кто это пишет

Честный ответ зависит от уровня

  1. Консультационный уровень

    Я читаю документы и комментирую их, объясняю, что в них должно быть, и даю prompt или задание, чтобы их подготовили. Проектную документацию как результат работы я на этом уровне не пишу.

  2. Уровень руководства

    Я требую документацию от команды, ставлю на неё задачу и принимаю результат. Я не пишу её вместо них.

  3. Вайб-кодинг

    Документация входит в поставку. Код, инфраструктура и важные решения записываются по ходу работы.

  4. Почему это различие важно

    Обещать документацию как результат на каждом уровне значило бы продавать то, чего в цене нет.

Чего ожидать

Не ожидайте

Стостраничного документа, написанного один раз и больше не обновляемого

Документации системы, которую я не читал

Написанных документов как результата на консультационном уровне

Ожидайте

Документы, достаточно короткие, чтобы их читали

Утверждения, которые можно проверить по работающей системе

Решения, записанные вместе с обоснованием, а не только с исходом

На верхнем уровне документацию, выкаченную вместе с работой

Начните с той области, которая беспокоит больше всего

Выберите подходящий уровень участия, опишите продукт, и мы начнём оттуда.