Ключевое - поддерживать документацию, но не писать ее. В этом все равно нельзя исключать человека. Код не всегда является истиной, требования часто меняются и, соответственно, документация тоже.
Понимаю, любые изменения обычно очень болезненные. Однозначно важно не только писать документацию, но и встроить её в процесс работы.
У нас я предприняла следующее:
сделала файл с описанием, как лучше писать документацию, на что обратить внимание
ревьюила все изменения в документации
если что-то было не так, я направляла ссылку на файлик и просила исправить по нему
В конечном итоге, я приучила разработчиков писать в нужном формате, хотя это и заняло достаточно много времени) естественно, иногда возникают небольшие вопросы к написанному, но я их обычно правлю самостоятельно, так как это быстрее.
В статье я как раз указывала, что ссылки на документацию помогают приучить людей читать. Если постоянно объяснять устно, возникает замкнутый круг: аналитик тратит время на повторения, а разработчики не привыкают обращаться к документации. Поэтому важно писать понятно и структурировано, чтобы ссылка реально работала, а не превращалась в «иди сам разбирайся».
Конечно, документация должна быть встроена в рабочий процесс.
Практика с ссылками на вики в задачах отличная, мы ее тоже используем. По поводу readme тоже согласна, как раз обсуждали с тимлидом, чтобы это ввести в процесс.
И, конечно, архитектура как код это однозначно best practice.
Спасибо за такой подробный разбор! Очень точное наблюдение о том, как информация подается конкретным людям в конкретной ситуации. Ваш пример со стиральной машинкой отлично показывает разницу между документацией для конструкторов и инструкцией для «рабочего».
Согласна, разработчику нужен краткий и понятный вход, с возможностью углубиться при необходимости. Обратная связь и разные форматы сильно с этим помогают.
Полностью поддерживаю, наблюдать, спрашивать и проверять, что реально удобно людям, гораздо эффективнее, чем просто создавать «талмуд» на все случаи жизни. Я писала статью как раз опираясь на свой опыт и обратную связь от разработчиков.
Вы описываете довольно логичный и зрелый подход — когда есть единая информационная модель проекта, а не просто набор разрозненных документов.
На практике, к сожалению, часто получается именно второй вариант: документы пишутся под конкретные задачи и со временем превращаются в «набор файлов по папкам».
ИИ здесь скорее попытка компенсировать эту разрозненность, а не решение корневой проблемы.
Так что мысль про движение в сторону единой структуры и модели отличная.
Про форматирование — прям в точку. Я это подразумевала в пункте про «единый стиль написания», но явно не выделила. Спасибо за дополнение)
Действительно, разработчик привык к структурированной информации. Поэтому я и отмечала в статье про важность правильного структурирования информации. Таблицы, списки, выделения, схемы сильно упрощают чтение.
Насчёт «разработчику достаточно кода» — частично согласна: код — это самый актуальный источник того, как система работает.
Но документация как раз дополняет код, а не заменяет его. Я считаю, лучший вариант когда код отвечает на «как», а документация на «почему» и «в каком контексте».
Это действительно довольно частый сценарий. Обычно это происходит, если задача «срочно сделать», а не «разобраться». И да, спросить часто быстрее, чем искать — особенно если поиск в документации устроен слабо.
Но насчёт «полезна на 10%» — тут, как по мне, многое зависит от того, как она устроена.
Если документация воспринимается как что-то большое, разрозненное и «на всякий случай», то действительно используется только малая часть. А вот если она разбита на небольшие, контекстные куски (условно те самые «несколько страниц в быстром доступе»), то процент использования резко растёт.
Про запоминание — тоже согласна: чтение само по себе почти не закрепляет знания. Поэтому документация, по сути, и не должна «учиться наизусть» — она должна быстро находиться в нужный момент.
Тогда она не будет «образованием ради галочки», а станет рабочим инструментом.
Спасибо за подробный комментарий! Крутой подход, особенно идея с «задача = отдельная страница» — это действительно сильно снижает когнитивную нагрузку и убирает необходимость ходить по всей документации в поисках ответа.
И, по сути, вы описываете то, к чему я тоже в итоге пришла: документация должна быть не «энциклопедией», а инструментом для выполнения конкретной задачи.
Про моменты «ответ в следующем абзаце» — да, это прям классика 🙂 И здесь как раз хорошо работает связка из структуры + привычки ссылаться на конкретное место, а не пересказывать.
Насчёт ИИ — согласна, что при хорошо организованной документации его ценность снижается. Но нельзя отрицать, он всё равно остаётся удобным слоем для навигации и быстрого входа, особенно для новых людей в команде.
Доверие к документации действительно легко потерять. Иногда проще пойти в код или спросить коллег. Но в этом и есть задача аналитика или технического писателя - поддерживать актуальность и точность описания.
Конечно, тот, кто пишет документацию должен быть хорошо подкован в техническом плане. Но это уже тема отдельной статьи, какими навыками должен обладать системный аналитик. Чаще всего это все-таки бывшие разработчики (я в том числе).
«Доверие есть только к исходному коду» - это справедливо в плане понимания реализации. Но код не всегда отвечает на вопрос «почему так сделано» и какие есть ограничения или договорённости.
Что касается LLM — согласна, это сильно упрощает доступ к информации. И идея делать документацию более «понятной для ИИ» звучит логично. Но, как мне кажется, это должна быть не замена, а помощь в работе.
Тем более если сама документация неактуальна или противоречива, ИИ просто будет быстрее распространять неточности и проблемы.
Согласна, текст действительно быстрее для получения информации.
Но на практике вопрос чаще не в скорости, а в привычке потребления. Как я и писала в статье, люди всё чаще привыкают получать информацию в визуальном формате. На этом фоне воспринимать сплошной текст становится сложнее, даже если он объективно эффективнее.
Интересная мысль, и в ней есть доля правды. ИИ уже сейчас активно используется как «прослойка» между разработчиком и документацией — чтобы быстрее найти ответ или собрать контекст.
Но я бы не стала рассматривать его как единственного читателя. Документация всё-таки фиксирует договорённости внутри команды: архитектурные решения, ограничения, причины «почему сделано так». Это то, что важно понимать человеку, а не только получить готовый ответ.
Думаю, сейчас мы движемся к модели:
документация пишется для людей, но с учётом того, что её будет также читать и интерпретировать ИИ
В любом случае советы, приведенные в статье, могут быть использованы для улучшения понимания текста ИИ.
Было бы интересно прочитать про этот проект)
Без валидации никуда, это точно.
Ключевое - поддерживать документацию, но не писать ее. В этом все равно нельзя исключать человека. Код не всегда является истиной, требования часто меняются и, соответственно, документация тоже.
Понимаю, любые изменения обычно очень болезненные. Однозначно важно не только писать документацию, но и встроить её в процесс работы.
У нас я предприняла следующее:
сделала файл с описанием, как лучше писать документацию, на что обратить внимание
ревьюила все изменения в документации
если что-то было не так, я направляла ссылку на файлик и просила исправить по нему
В конечном итоге, я приучила разработчиков писать в нужном формате, хотя это и заняло достаточно много времени) естественно, иногда возникают небольшие вопросы к написанному, но я их обычно правлю самостоятельно, так как это быстрее.
В статье я как раз указывала, что ссылки на документацию помогают приучить людей читать. Если постоянно объяснять устно, возникает замкнутый круг: аналитик тратит время на повторения, а разработчики не привыкают обращаться к документации. Поэтому важно писать понятно и структурировано, чтобы ссылка реально работала, а не превращалась в «иди сам разбирайся».
Спасибо за советы!
Конечно, документация должна быть встроена в рабочий процесс.
Практика с ссылками на вики в задачах отличная, мы ее тоже используем. По поводу readme тоже согласна, как раз обсуждали с тимлидом, чтобы это ввести в процесс.
И, конечно, архитектура как код это однозначно best practice.
Спасибо за такой подробный разбор! Очень точное наблюдение о том, как информация подается конкретным людям в конкретной ситуации. Ваш пример со стиральной машинкой отлично показывает разницу между документацией для конструкторов и инструкцией для «рабочего».
Согласна, разработчику нужен краткий и понятный вход, с возможностью углубиться при необходимости. Обратная связь и разные форматы сильно с этим помогают.
Полностью поддерживаю, наблюдать, спрашивать и проверять, что реально удобно людям, гораздо эффективнее, чем просто создавать «талмуд» на все случаи жизни. Я писала статью как раз опираясь на свой опыт и обратную связь от разработчиков.
Надеюсь, я верно поняла вашу мысль.
Вы описываете довольно логичный и зрелый подход — когда есть единая информационная модель проекта, а не просто набор разрозненных документов.
На практике, к сожалению, часто получается именно второй вариант: документы пишутся под конкретные задачи и со временем превращаются в «набор файлов по папкам».
ИИ здесь скорее попытка компенсировать эту разрозненность, а не решение корневой проблемы.
Так что мысль про движение в сторону единой структуры и модели отличная.
Про форматирование — прям в точку. Я это подразумевала в пункте про «единый стиль написания», но явно не выделила. Спасибо за дополнение)
Действительно, разработчик привык к структурированной информации. Поэтому я и отмечала в статье про важность правильного структурирования информации. Таблицы, списки, выделения, схемы сильно упрощают чтение.
Насчёт «разработчику достаточно кода» — частично согласна: код — это самый актуальный источник того, как система работает.
Но документация как раз дополняет код, а не заменяет его. Я считаю, лучший вариант когда код отвечает на «как», а документация на «почему» и «в каком контексте».
Это действительно довольно частый сценарий. Обычно это происходит, если задача «срочно сделать», а не «разобраться».
И да, спросить часто быстрее, чем искать — особенно если поиск в документации устроен слабо.
Но насчёт «полезна на 10%» — тут, как по мне, многое зависит от того, как она устроена.
Если документация воспринимается как что-то большое, разрозненное и «на всякий случай», то действительно используется только малая часть.
А вот если она разбита на небольшие, контекстные куски (условно те самые «несколько страниц в быстром доступе»), то процент использования резко растёт.
Про запоминание — тоже согласна: чтение само по себе почти не закрепляет знания.
Поэтому документация, по сути, и не должна «учиться наизусть» — она должна быстро находиться в нужный момент.
Тогда она не будет «образованием ради галочки», а станет рабочим инструментом.
Спасибо за подробный комментарий! Крутой подход, особенно идея с «задача = отдельная страница» — это действительно сильно снижает когнитивную нагрузку и убирает необходимость ходить по всей документации в поисках ответа.
И, по сути, вы описываете то, к чему я тоже в итоге пришла:
документация должна быть не «энциклопедией», а инструментом для выполнения конкретной задачи.
Про моменты «ответ в следующем абзаце» — да, это прям классика 🙂
И здесь как раз хорошо работает связка из структуры + привычки ссылаться на конкретное место, а не пересказывать.
Насчёт ИИ — согласна, что при хорошо организованной документации его ценность снижается.
Но нельзя отрицать, он всё равно остаётся удобным слоем для навигации и быстрого входа, особенно для новых людей в команде.
Доверие к документации действительно легко потерять. Иногда проще пойти в код или спросить коллег. Но в этом и есть задача аналитика или технического писателя - поддерживать актуальность и точность описания.
Конечно, тот, кто пишет документацию должен быть хорошо подкован в техническом плане. Но это уже тема отдельной статьи, какими навыками должен обладать системный аналитик. Чаще всего это все-таки бывшие разработчики (я в том числе).
«Доверие есть только к исходному коду» - это справедливо в плане понимания реализации. Но код не всегда отвечает на вопрос «почему так сделано» и какие есть ограничения или договорённости.
Что касается LLM — согласна, это сильно упрощает доступ к информации. И идея делать документацию более «понятной для ИИ» звучит логично. Но, как мне кажется, это должна быть не замена, а помощь в работе.
Тем более если сама документация неактуальна или противоречива, ИИ просто будет быстрее распространять неточности и проблемы.
Согласна, текст действительно быстрее для получения информации.
Но на практике вопрос чаще не в скорости, а в привычке потребления. Как я и писала в статье, люди всё чаще привыкают получать информацию в визуальном формате. На этом фоне воспринимать сплошной текст становится сложнее, даже если он объективно эффективнее.
Думаю, добавление визуала (схем, диаграмм) поможет быстрее понять написанный текст.
Плюс, конечно, многое упирается в качество самой документации — если она плохая, её начинают избегать независимо от формата.
Интересная мысль, и в ней есть доля правды. ИИ уже сейчас активно используется как «прослойка» между разработчиком и документацией — чтобы быстрее найти ответ или собрать контекст.
Но я бы не стала рассматривать его как единственного читателя.
Документация всё-таки фиксирует договорённости внутри команды: архитектурные решения, ограничения, причины «почему сделано так». Это то, что важно понимать человеку, а не только получить готовый ответ.
Думаю, сейчас мы движемся к модели:
В любом случае советы, приведенные в статье, могут быть использованы для улучшения понимания текста ИИ.