Хабр Курсы для всех
РЕКЛАМА
Практикум, Хекслет, SkyPro, авторские курсы — собрали всех и попросили скидки. Осталось выбрать!
Хабр доступен 24/7 благодаря поддержке друзей
Комментарии 39
Документацию нужно адаптировать под ИИ, потому что в скором времени он и только он будет ее читать
Интересная мысль, и в ней есть доля правды. ИИ уже сейчас активно используется как «прослойка» между разработчиком и документацией — чтобы быстрее найти ответ или собрать контекст.
Но я бы не стала рассматривать его как единственного читателя.
Документация всё-таки фиксирует договорённости внутри команды: архитектурные решения, ограничения, причины «почему сделано так». Это то, что важно понимать человеку, а не только получить готовый ответ.
Думаю, сейчас мы движемся к модели:
документация пишется для людей, но с учётом того, что её будет также читать и интерпретировать ИИ
В любом случае советы, приведенные в статье, могут быть использованы для улучшения понимания текста ИИ.
Однако текст читать быстрее чем смотреть видео или слушать подкасты.
Ну, если кто грамоте обучен, конечно.
В остальном да, не читают, не могут.
Согласна, текст действительно быстрее для получения информации.
Но на практике вопрос чаще не в скорости, а в привычке потребления. Как я и писала в статье, люди всё чаще привыкают получать информацию в визуальном формате. На этом фоне воспринимать сплошной текст становится сложнее, даже если он объективно эффективнее.
Думаю, добавление визуала (схем, диаграмм) поможет быстрее понять написанный текст.
Плюс, конечно, многое упирается в качество самой документации — если она плохая, её начинают избегать независимо от формата.
Разработчики никогда не любили читать документацию, ещё до времён тиктоков. Потому что пишут её люди, к которым нет ни доверия ни уважения (как к технарям). Достаточно пару раз напороться на неактуальность и ошибки, и всё, доверия нет. Доверие есть только к исходному коду. А сами разработчики документацию писать не любят. LLM в этом плане просто спасение.
Замените все эти пункты на "убедиться, что документация доступна через MCP и сформирована понятным для ИИ образом". Всё остальное в топку.
Доверие к документации действительно легко потерять. Иногда проще пойти в код или спросить коллег. Но в этом и есть задача аналитика или технического писателя - поддерживать актуальность и точность описания.
Конечно, тот, кто пишет документацию должен быть хорошо подкован в техническом плане. Но это уже тема отдельной статьи, какими навыками должен обладать системный аналитик. Чаще всего это все-таки бывшие разработчики (я в том числе).
«Доверие есть только к исходному коду» - это справедливо в плане понимания реализации. Но код не всегда отвечает на вопрос «почему так сделано» и какие есть ограничения или договорённости.
Что касается LLM — согласна, это сильно упрощает доступ к информации. И идея делать документацию более «понятной для ИИ» звучит логично. Но, как мне кажется, это должна быть не замена, а помощь в работе.
Тем более если сама документация неактуальна или противоречива, ИИ просто будет быстрее распространять неточности и проблемы.
Opus прекрасно поясняет код и отвечает на большинство вопросов по нему. На много лучше, чем условный аналитик, большинство из которых код не открывают от слова вообще. Вот эта людская роль - в top 3 на вылет.
Тем более если сама документация неактуальна или противоречива, ИИ просто будет быстрее распространять неточности и проблемы.
Нет. У LLM будет доступ как к исходному коду, так и к документации (вопросы СБ давайте оставим за скобками). Причём документацию сам же LLM и будет поддерживать в актуальном состоянии. Для этого человек УЖЕ не нужен. Осталось только доступ к современным моделям распространить в массы, идеально, если в self hosted виде. Только это пока ограничивает.
Мне тоже в статье про ведение документации начали писать, что уметь грамотно ее вести не так важно, если сейчас все делает ИИ. На самом деле, если правильно все сделать, то ИИ и не нужен будет.
В целом, я описал частично в своей статье, но чтобы вам не пришлось лезть, кратко объясню: я организую всю документацию на разных страницах-артефактах в вики, так как таким образом это не превращается в длинное полотно на 30-100 страниц, в этом легче ориентироваться и гораздо легче поддерживать. И да, каждая задача для разработчика — это отдельная страница. Ему вообще с нее не нужно уходить: там все описано, что нужно для конкретной задачи, а ссылки на другие страницы — дополнительная информация, если вдруг разработчик решит почитать, но это не обязательно для выполнения задачи.
У меня была проблема в первом ТЗ для разработчиков на этом месте работы, что ко мне приходили с вопросами "А это как делать?". Но чаще всего эти вопросы решались тем, что я указывал на какой-то абзац на той же странице задачи. Нет, задача не написана на 10 страниц, там максимум набирается страницы 2, но обычно — меньше страницы. Вся документация строго структурирована и никакой воды в ней нет: только инструкции, что сделать. Был момент, когда ко мне бэкендерша пришла с вопросом, на который был ответ буквально в следующем абзаце. Она просто не дочитала.
После работы со мной в рамках первого требования, разработчики все поняли и больше с такими вопросами не приходят)
Вообще считаю, что каждая вики должна иметь возможность вставить видео с сабвей серферс справа от статьи, чтобы удерживать внимание разработчиков)
Ещё раз - MCP нужен не для того, что бы ИИ пересказал документацию простыми словами и по сути (хотя и это тоже), он нужен для того, что бы ИИ сгенерировал по документации сходу правильный код.
Ожидание, что талмуд документации прочитают, запомнят, и не будут приходить с вопросами - это что-то запредельное по своей неправильности. Это можно ожидать от машины, люди - существа с быстро деградирующей памятью. Минусуйте..
У меня недостаточно кармы, чтобы минусовать, да я и не собирался)
Согласен, что подобная возможность круто смотрится. Но только с MCP, потому что если просто в отрыве от контекста отправить тзшку, то можно накодить неправильно. Хотя в большинстве своем справится
У нас на работе, к сожалению, нет встроенного в wiki ИИ. Все обещают сделать что-то свое, но пока никак. MCP для wiki подключить, конечно же, никто не даст, потому что правила безопасности не позволяют. Можно пользоваться гптшками, но не сильно погружая ее в контекст (нельзя всю базу кодовую слить)
Многое в СБ упирается
MCP - это примитивнейший протокол, реализовать его на коленке можно. Тут вопрос в самой реализации работы с данными - что именно он выдаёт и как. Самые простые кейсы - это технические описания API методов и т.п., банально куски текста можно пробрасывать, LLM на раз такое сжуёт и будет применять при кодогенерации. В том числе, запихивая в контекст и нюансы использования. Будет написано в документации в поле "color" зелёный пихать нельзя - она это учтёт, а вот человек наверняка пропустит, ибо никто не читает доки слово в слово.
Сложнее с автоматизацией всякой логики, но и то, если её можно описать dataflow / UML диаграммами - это всё можно в MD виде через MCP отдать и нормальная LLM с этим тоже работает.
В общем, тут меняются требования к самой документации, но ключевое - она начнёт работать, а не всё это...
Вы очень четко описали документацию, которую я читать не буду! Организация в режиме вики лично для меня категорически не удобная. Особенно если знакомишься с новым продуктом, особенно если нету последовательного повествования, с погружением в специфику продукта. Какие-то артефакты, которые разработчик продукта посчитал важными он описал, а последовательное пояснение с чего начать, как установить, как использовать и т.п. как правило хрен найдёшь в это вашей вики. Оговорюсь, в том случае если мы говорим про документацию, а не базу знаний. И даже в случае базы знаний, я не буду читать статью/артефакт, потом прыгать за другим артефактом по ссылке, потом за другим и так далее.
Спасибо за подробный комментарий! Крутой подход, особенно идея с «задача = отдельная страница» — это действительно сильно снижает когнитивную нагрузку и убирает необходимость ходить по всей документации в поисках ответа.
И, по сути, вы описываете то, к чему я тоже в итоге пришла:
документация должна быть не «энциклопедией», а инструментом для выполнения конкретной задачи.
Про моменты «ответ в следующем абзаце» — да, это прям классика 🙂
И здесь как раз хорошо работает связка из структуры + привычки ссылаться на конкретное место, а не пересказывать.
Насчёт ИИ — согласна, что при хорошо организованной документации его ценность снижается.
Но нельзя отрицать, он всё равно остаётся удобным слоем для навигации и быстрого входа, особенно для новых людей в команде.
В идеальной вики я бы видел ИИ, который привязан к гит с кодом проекта. Я использую подобное для пет проекта и это отлично позволяет составлять документацию: тебе по сути ничего делать не надо, просто даешь ему шаблоны и он заполняет, какие изменения нужно делать. Жаль для рабочей документации так делать нельзя 🥲
Конечно, нужно валидировать, но все же это гораздо быстрее (порой недели могут сократиться до часов). Осталось только его BPMN-диаграммы рисовать, с Mermaid-диаграммами он и так отлично справляется)
Так что ИИ полезен не только для чтения документации, но и для ее написания. Но опять-таки, все нужно валидировать, а если на странице вся задача написана, то ИИ в целом может и не понадобиться
Документацию читают. Просто по диагонали.
Документация — она как образование, времени тратит много, а полезна процентов на 10%.
Все понимают, что спросить — быстрее чем искать в документации. Поиск, вероятно, плох, что и правда будет правиться нейронками с векторными бд.
А ещё после прочтения документации — она не запоминается. Точнее запоминается, но не так сильно, как при составлении. Решается это как и в школе, экзамены, да хоть уроки. В противном случае, аналитик составлял документацию для себя, чтобы служить для нее поисковиком.
На практике все не так плохо, и несколько страниц доки есть в быстром доступе. Просто это те самые 10% и они не обязательно одинаковые для разных людей.
Это действительно довольно частый сценарий. Обычно это происходит, если задача «срочно сделать», а не «разобраться».
И да, спросить часто быстрее, чем искать — особенно если поиск в документации устроен слабо.
Но насчёт «полезна на 10%» — тут, как по мне, многое зависит от того, как она устроена.
Если документация воспринимается как что-то большое, разрозненное и «на всякий случай», то действительно используется только малая часть.
А вот если она разбита на небольшие, контекстные куски (условно те самые «несколько страниц в быстром доступе»), то процент использования резко растёт.
Про запоминание — тоже согласна: чтение само по себе почти не закрепляет знания.
Поэтому документация, по сути, и не должна «учиться наизусть» — она должна быстро находиться в нужный момент.
Тогда она не будет «образованием ради галочки», а станет рабочим инструментом.
Вообще документация для аналитика, разработчику обычно достаточно кода, это самая актуальная документация
Я бы ещё отметил что постановки задач и документация часто пишется без должного форматирования текста, игнорирование таблиц, хотя последние хорошо структурируют данные. Разработчик привык видеть разноцветный код, имеющий определенную структуру, множетсво отступов и смотреть на безжизненный текст в виде сочинения пятиклассника "Как я провел лето" ужасное занятие.
Пожалуйста, а можно пример? Какую-нибудь картинку, как по структуре, по оформлению должно выглядеть задание, которое вам будет удобно читать? Реально очень интересно.
Не думаю, что возможно описать все одной картинкой.
Для постановок на разработку должен быть выработан свой фреймворк, понятное дело, что четких границ нельзя задать, так как нет компилятора или интерпретатора который все это проверит, но все должно повторяться от одной задаче к другой. Я бы сказал, что это должна быть более высокоуровневая абстракция над кодом.
Название, описание действий, структура данных, валидация, роли, действующие лица, джобы, события. Это все можно поместить в таблицы. Чаще всего это crud, я бы назвал crud+, когда есть множество действий но почти все они основаны на действии update или это какие либо сценарии, где мы обновляем данные.
«Если ваш код слишком сложен для того, чтобы вписаться в парадигму CRUD — значит, вы делаете что-то не так.» Я не помню откуда это, но чем больше работаю разработчиком, тем больше верю в эти слова.
К словам о crud+, я бы ещё добавил state machine, это те два столпа на которых можно построить что угодно, сохранив системность.
Да, да, наверное, это примерно так, как я вижу (я не кодер, "половину слов не понял", но примерно догадываюсь). Ниже накатал простыню - не отсылаю к ней (экономьте свое время), но мне кажется, что разработка должна вестись от проекта как общей информационной модели. В терминах ООП (попытаюсь привести понятную кодеру аналогию) вы рассматриваете ПО как объект, строите его инф.модель примерно как класс, с этого "скелета" снимаете информацию о конкретной версии (та самая "абстракция над кодом"). Если у вас информация о проекте структурирована и лежит в одной базе (пока промолчу про интегрированные базы) - поддерживается и "актуальность", и "непротиворечивость", и можно выгрузить "что нужно в удобной форме". И можно использовать "от одной задачи к другой". Даже если у вас еще нет автоматизации уровня "БД с интерфейсом" - хотя бы начинать лежать в том направлении, грубо, уровня "отдельные таблички Эксель". Пока же выглядит так (может, я чего-то не понимаю), что "мы просто взяли кучу каких-то бумажных документов, описывающих проект, даже не полностью (по лохматым стандартам), а как показалось удобно, оцифровали, рассовали по папкам и вставили немножко ссылок". И вся эта бумага - вида "конструкторская документация для конструкторов". Там, кажется, нет даже документации типа "задание для исполнителя" (аналог "карта-наряд для рабочего"), хотя кодер уже не тот, кто "делает весь код по всему проекту", а по факту "рабочий, который пилит свой маленький кусочек и очень быстро". И предложение быстренькой-удобненькой автоматизации - давайте пустим к куче этой макулатуры ИИ, который на нее основе нам вероятностно нагенерит нужный текст. На полном серьезе.
Надеюсь, я верно поняла вашу мысль.
Вы описываете довольно логичный и зрелый подход — когда есть единая информационная модель проекта, а не просто набор разрозненных документов.
На практике, к сожалению, часто получается именно второй вариант: документы пишутся под конкретные задачи и со временем превращаются в «набор файлов по папкам».
ИИ здесь скорее попытка компенсировать эту разрозненность, а не решение корневой проблемы.
Так что мысль про движение в сторону единой структуры и модели отличная.
Про форматирование — прям в точку. Я это подразумевала в пункте про «единый стиль написания», но явно не выделила. Спасибо за дополнение)
Действительно, разработчик привык к структурированной информации. Поэтому я и отмечала в статье про важность правильного структурирования информации. Таблицы, списки, выделения, схемы сильно упрощают чтение.
Насчёт «разработчику достаточно кода» — частично согласна: код — это самый актуальный источник того, как система работает.
Но документация как раз дополняет код, а не заменяет его. Я считаю, лучший вариант когда код отвечает на «как», а документация на «почему» и «в каком контексте».
Выскажу свои мысли, "почему" и "как наверное можно решить", но сразу предупрежу - они с очень специфической колокольни, и могут показаться глупыми, усложняющими и т.п. И в целом мои предположения как у "дефективной совы" - "мыши, станьте ежиками". Мне бы хотелось мыслей от работающих в отрасли ("да, это совсем глупости, потому что"). Возможно, я наивное дитя с крайнего чего-то там, который пришел к серьезным дядям, стал отвечать на риторические вопросы и на полном серьезе полез разбираться с идеями "сферических коней в вакууме" – тоже вариант. Но мне, правда, любопытно, "что творится-то". На всякий – никого не хочу обидеть или оскорбить. Острожно, лонгрид!
Может, дело не в лени разработчиков и качестве отдельной документации, а в организации (в реализации автоматизации бизнес-процесса)? Нет, я не с критикой, не о том, что "у вас все плохо" - но если что-то не работает, может попробовать "зрить в корень" и поискать, "где собака зарыта"?
Вы пишете о документации, как говорили в древности, "рабочего проекта". Рабочий проект - это описание информационной модели продукта, на основе которой делается продукт реальный. Общий тип процесса работает с древнейших времен и применяется даже вашими кодерами чуть не ежедневно. Чертеж и смета - документы проекта сарая, по ним строим сарай. Есть класс объекта - по нему делается конкретный объект (в ООП). И стиральную машинку на заводе тоже будут собирать примерно так же, единственное ключевое отличие - стиральную машинку вы какое-то время штампуете по утвержденной и не меняющейся документации на модель, потом конструкторам ставят новое задание (например, помечтаем, обратная связь от потребителей), они делают документацию на новую модель, и вы штампуете уже ее. А в современной разработке ПО процесс изменений почти постоянный, так что у вас конструкторское бюро, завод и отдел работы с заказчиками/потребителями "в одном флаконе".
Когда продукт не сложный, пет-проект, стартап на 3 человек – это аналог "кустарного производства". Да, тут иногда срабатывает и "вообще без документации" – сарай можно построить и без чертежа, на глаз, из горы досок. И организация команды "Вася поговорил с Петей" отлично работает. Но современное ПО уже делается десятком разработчиков, с разделением ролей в команде, очень быстро. И организационно все превращено в "конвеер" (я не про "унизить разработчика", я о том, что при производстве сложного ПО, как и при производстве сложной техники, используют разделение труда). Задача ставится короткая и узкая – зато ее можно сделать быстро и потом собрать в общую работу (узнаете принцип?).
И тут, признаться, я несколько впадаю в ступор. Я представляю, как производство стиральной машинки (а это довольно простая быт.техника) организовано так, что документация на нее лежит в... вики. И конструкторы правят все в... вики. И рабочего посылают смотреть, что ему делать, в... вики. Единой. Для всех. И, достижение – задание рабочего лежит в одной-двух страничках (как тут в комменте выше), а не в ста. Но современное ПО часто уже даже не стиральная машинка, а минимум автомобиль!
Я представляю себе рабочего, которому дают не карту-наряд, где расписано: "берешь деталь А1, берешь гвоздь Б2 и молоток М3, вбиваешь гвоздь в отверстие 4 детали А1", а отсылают к талмуду на 100, а то и 1000 страниц, описывающему всю "машинку". Даже если талмуд не в одном файле с разделами, или с десятке документов, в структурированном формате вики. Рабочий пойдет читать? Даже если это прекрасно написанная, четкая и подробная документация, от которой все конструкторы в восторге? Нет. Не пойдет. Такая документация – прежде всего для конструкторов. Она не для рабочего – не та "целевая аудитория". И она описывает весь проект. В целом. А рабочему нужно не описание всей "стиральной машинки", а краткая инструкция (а "как гвозди типа Б вбиваются в детали типа А" – вот ссылка на раздел руководства, забудет – посмотрит).
Я ни в коем случае не хочу унизить кодеров, сравнивая с рабочими. Я о том, что оба работают в дефиците ресурсов. Рабочему надо "быстро". Кодеру надо "быстро и кратко" – у него и релиз "горит", и информационный перегруз бывает.
В чем по идее сложность по сравнению с "заводом"? Там документация меняется медленнее, потому тех.писатель написал инструкцию, потом подправил ее через несколько месяцев. Тут – быстро (иногда чуть не "утром заявка, через час правка, через два обновление"). Но смотрим на автоматизацию заводов, как у них стараются организовать. Информация об объекте (продукте, процессе) кладется в базу данных. И из базы, где хранится информационная модель объекта, данные выгружаются в конкретные документы по шаблонам. Мало того, системы, описывающие разные информационные модели продукта, интегрируются. А хранить в структурированных папках или вики – прикиньте, какой это примерно год или какие по размеру предприятия (и их продукты).
То есть, с моей колокольни, "сапожнику надо подумать, как сшить себе домашние тапочки". А попросту – применить уже имеющиеся у вас в компании "скиллы" на практике. К себе. Причем у вас задачка в чем-то попроще – вы сами живете "внутри" бизнес-процесса, его участники и спецы, чтобы поправить – у вас под рукой.
Если кодеры не читают документацию – для начала, может, хотя бы спросить, в каком виде им удобнее получать данные? Конкретно у вас, а не "в общем". Где затык? Объем? Форма? Подача? Содержание? Может, у вас разные "типы" кодеров по задачам – одним нужно "задание" в одном виде, другим "в другом". Посмотреть, проверить, что и им не нравится, на что уходит время. Может, неясно написано. Может, проблема в актуализации. Может вообще в какой-то мелочи – ну там "в вики шрифт слишком мелкий" (нет, сделать крупным – не факт что сами догадаются. "Не нравится документация" может на самом деле означать "не нравится интерфейс, потому стараюсь смотреть меньше / запоминаю хуже", проблема "неусвоения информации" может таиться и в таком). Я просто вспоминаю, что иногда проблемы и затыки на реальном производстве решались какими-то простейшими изменениями – стул поменяли, лампу передвинули; потом даже целую науку эргономику создали. А кто решает проблемы "затыков" с информацией? Бизнес- и системные аналитики, так вроде?
А дальше примерно так же, как с автоматизацией заводов, которые когда-то были кустарными мастерскими с единичным выпуском (а где-то и сейчас есть, вроде "Тачки на прокачку"). Я не призываю ставить в мастерскую "с 2 калеками" ERP, и прыгать в автоматизации через 10 ступенек сходу. Но анализ узких мест и поиск проблем – это лохматейшая классика и скилл, который под рукой. Почему его не использовать, если действительно нужно решить проблему? (Да-да, "можно, а зачем?", "у меня времени нет / мне за это не платят", и "я просто пожаловаться, а ты всерьез, инопланетянин" – это я знаю :) ).
Как вы думаете, в эту простыню есть желание вчитываться? Глаза просто убегают от этого текста. Он психологически некомфортен по своему формату. Выше хорошо описали, почему. Вот потому и документацию в таком виде желания читать тоже никакого.
Именно. Видите, я высказал свои мысли так, как мне было удобно (с температурой глухой ночью) и максимально подробно. Для меня этот лонгрид сырого текста удобен. Но если я изменю только форматирование - оно все равно останется непрочитанным лонгридом, на лонгрид время не тратят априори. Можно было бы написать совсем кратко - "нужно реальное решение - используйте имеющиеся скиллы". Что я тогда получу? 99% - игнор, 1% - вопрос "вы о чем" с долгим разжевыванием (т.е. лишнюю трату своего времени на выдачу того же текста, но кусками).
Спасибо за такой подробный разбор! Очень точное наблюдение о том, как информация подается конкретным людям в конкретной ситуации. Ваш пример со стиральной машинкой отлично показывает разницу между документацией для конструкторов и инструкцией для «рабочего».
Согласна, разработчику нужен краткий и понятный вход, с возможностью углубиться при необходимости. Обратная связь и разные форматы сильно с этим помогают.
Полностью поддерживаю, наблюдать, спрашивать и проверять, что реально удобно людям, гораздо эффективнее, чем просто создавать «талмуд» на все случаи жизни. Я писала статью как раз опираясь на свой опыт и обратную связь от разработчиков.
Поздравляю вас с вступлением в этот мир боли :)
Неприятно, конечно, как Кафка писать «в стол».
Но могу вам дать ещё парочку советов с точки зрения РП и техлида:
договоритесь с тимлидом и пусть он настаивает и проверяет - в каждой задаче должна быть ссылка на вики
В функциональных методах должна быть ссылка на вики или задачу
В папках проекта должен быть read.me файл либо с описанием содержимого, либо снова с ссылкой нс документ.
Введите structurizr для С4. программистам намного проще сопровождать архитектуру с подходом architecture as code
В том же dsl описываются deployment инфраструктура стендов. Можно делать сетевые карты, в props писать порты и ip
Вы сами сказали проблему — вас спрашивают, где искать документ, потому что про его существование либо не знают, либо он не под рукой. Быть «справочным бюро» и бесит и создаётся ощущение, что работа аналитика не важна и не ценится.
Но проблема именно в этой связке - нет никаких проблем создавая метод в коменте к нему добавлять ссылку на задачу. Ничего не стоит при декомпозиции добавлять ссылку на вики в задачу. Сопровождать диаграммы в виде кода, а не тыкаясь в редакторе графическом намного проще и их потом можно парсить и выдавать удобно таблицы сетевых связей, например, компонентов, списки ролей и к чему у них есть доступ. Их все равно потом требует ИБ, а программисты ленивы, если они поймут, что проще такие задачи решать имея С4 в виде кода, они будут так делать.
С этой бюрократией тоже надо осторожно. Да и вообще с "разрешительными вертикалями" . Когда проект доходит до стадии "любое изменение - через задачу", вот тогда и начинает комом расти технический долг и проект начинает превращаться в легаси. Если в проекте вдруг менеджер и аналитик становятся desicion wall, то это убивает любую инициативу со стороны программистов. А именно программистам видно, где и что было бы хорошо бы поправить и в гробу многие видели ходить к менеджеру и аналитику за разрешением порефакторить и что-то изменить, и тем более, описывать всё это в вики, которую никто и читать не будет в итоге.
В общем, балансировать надо в этих вопросах. В одном проекте мы договорились, что 10% времени программеры могут тратить на работу по своему усмотрению и ни с кем не обязаны её согласовывать ранее PRов. Речь не про публичные контракты данных конечно.
Спасибо за советы!
Конечно, документация должна быть встроена в рабочий процесс.
Практика с ссылками на вики в задачах отличная, мы ее тоже используем. По поводу readme тоже согласна, как раз обсуждали с тимлидом, чтобы это ввести в процесс.
И, конечно, архитектура как код это однозначно best practice.
Если аналитику самому понятно, что он написал, он с удовольстием откроет документацию вместе с разработчиком, и покажет все и объяснит. Но если этого не происходит, значит аналитику либо не понятно самому и лень разбираться, либо не интересно, что он сам написал. Либо он просто уже забыл сам и запутался. Отсылка к документации, равносильна отсылке на три буквы.. Типа я там написал что-то.. иди разбирайся.. мне уже пофигу...
То есть качество документации проверяется в первую очередь на самом авторе, чтобы быстро что то вспомнить и объяснить. Если его не читают, - значит непонятно пишет.
В статье я как раз указывала, что ссылки на документацию помогают приучить людей читать. Если постоянно объяснять устно, возникает замкнутый круг: аналитик тратит время на повторения, а разработчики не привыкают обращаться к документации. Поэтому важно писать понятно и структурировано, чтобы ссылка реально работала, а не превращалась в «иди сам разбирайся».
Соблюдайте единый стиль написания
Когда стиль единый, проще ориентироваться и искать нужную информацию. Сформируйте для себя шаблоны, общую структуру описания и следуйте ей в каждом новом файле. Оставляйте внутри перекрестными ссылки и якори на другие разделы, чтобы было проще искать более подробную информацию.
Используйте инструменты с версионированием
Word — не лучший формат для живой документации. Лучше использовать инструменты, которые поддерживают версионирование и интеграцию с процессом разработки: wiki-системы или Markdown в репозитории. Так намного проще отследить изменения и откатить все обратно.
Придерживайтесь иерархии
Человек намного лучше воспринимает иерархически организованную информацию, чем сплошной текст. Используйте разделы, подразделы и оглавление для удобства поиска и восприятия. Однако важно не переусердствовать с дроблением, слишком глубокая вложенность может запутать. Если информации слишком много, то лучше разделить ее на разные области контекста и уже внутри них выстроить иерархию.
Самые "больные" пункты. Сколько я не пытался приучить коллег к использованию MD+Git+Зфтвщс, использовать сниппеты и единый стиль, все бесполезно.
Каждый документ как сочинение "Как я провёл лето", написанное пятиклассником.
Понимаю, любые изменения обычно очень болезненные. Однозначно важно не только писать документацию, но и встроить её в процесс работы.
У нас я предприняла следующее:
сделала файл с описанием, как лучше писать документацию, на что обратить внимание
ревьюила все изменения в документации
если что-то было не так, я направляла ссылку на файлик и просила исправить по нему
В конечном итоге, я приучила разработчиков писать в нужном формате, хотя это и заняло достаточно много времени) естественно, иногда возникают небольшие вопросы к написанному, но я их обычно правлю самостоятельно, так как это быстрее.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Почему разработчики перестали читать документацию и что с этим делать