Technical-Writing

Я участвовал во множестве совещаний, где кто-нибудь говорил: «Подождите, почему мы сделали это именно так?», только чтобы обнаружить, что ответ был спрятан в 47-страничном RFC 2019 года, который никто никогда не открывал. Звучит знакомо? Ирония заключается в том, что документы RFC должны предотвращать этот хаос. Вместо этого многие команды создают RFC, которые бегло просматриваются, неправильно понимаются или, что ещё хуже, полностью игнорируются. Но вот в чём дело: хорошо составленный RFC — это как хороший фильм....

Тихая смерть технического контента Вы знаете этот момент, когда вы натыкаетесь на страницу документации, начинаете читать, и уже к третьему абзацу ваши глаза стекленеют? Вы не одиноки. Где-то в канале Slack прямо сейчас разработчик печатает: «Кто-нибудь читал эту документацию? Я так запутался». Суровая правда: большинство технических материалов не работает не потому, что они неверны, а потому, что забывают, что их будут читать люди — реальные, уставшие, нетерпеливые люди. Мы пишем так, как будто роботы объясняют физику другим роботам, вместо того чтобы преодолеть разрыв между «я это глубоко понимаю» и «я могу объяснить это тому, кто не понимает»....

Представьте: вы знакомите нового разработчика с проектом, и вместо того чтобы сесть за чашечкой кофе и поделиться знаниями, вы даёте ему ссылку на вики-страницу, созданную с помощью ИИ, и говорите: «Всё, что тебе нужно, там». Через шесть месяцев он всё ещё борется с теми же пробелами в знаниях, которые не может заполнить ни один, даже идеально оформленный Markdown-файл. Знакомо? Мы живём в эпоху того, что я называю Великим обманом документации — опасного мифа о том, что документация, созданная с помощью ИИ, может заменить хаотичный, человеческий и бесценный процесс обмена знаниями....