Блогеры-программисты совершают одни и те же ошибки: от скучного вступления до нечитаемого шрифта
Anti-Patterns in Software Blogging
Автор собрал антипаттерны в техническом блогинге, которые чаще всего встречаются у начинающих. Главный из них — многословное вступление: читатель должен понять за первые три предложения, чем статья полезна именно ему. Также в списке — избыток ссылок, требующих от читателя дополнительного чтения, предположение, что он уже знаком с предыдущими постами, излишняя формальность и базовые ошибки вёрстки: переполнение экрана на мобильных и низкий контраст текста. Автор подчёркивает: пишите так, как говорите, и проверяйте статью в мобильном режиме браузера.
Самый распространённый промах в техническом блогинге, безусловно, — это многословность. Я постоянно ловлю себя на том, что читаю уже несколько абзацев, а всё ещё не понимаю, что автор пытается мне сказать.
- phreack
Я всегда настаиваю, что образование — это не сторителлинг, и его не следует так структурировать. Люди хотят приберечь «твисты» и «откровения» для максимального эффекта, и это вредно. На самом деле должно быть наоборот — и, продолжая тему, «спойлерно» и повторяюще. Как в хорошей презентации, нужно начать с того, что вы скажете, сказать это, а затем закончить тем, что вы сказали.
LLM сделали эту проблему чрезвычайно хуже. Представьте, как бы вы объяснили, что такое MCP, в паре слов и технически, а затем попробуйте найти это. Там телефонные книги страниц и текста, которые никогда не доходят до сути.
- jrochkind1
В некоторые недели мне кажется, что большинство программных блогов, которые я вижу, теперь написаны LLM. Обычно они ужасны.
Может, кто-нибудь расскажет LLM об этих антипаттернах, серьёзно, это помогло бы?
Я, конечно, предпочёл бы, чтобы люди сами писали текст, который, как они ожидают, я, человек, буду читать.
- ram1500natrluvr
«Блуждающее вступление» — возможно, самая распространённая ошибка, безусловно, но самая вредная ошибка, безусловно, — это неспособность связать тему с чем-то, с чем читатели знакомы (антипаттерн №2). Некоторые вещи просто требуют определённого уровня экспертизы/предварительных знаний, чтобы начать понимать, но я неоднократно видел в программных блогах, README и т.д. неспособность ответить на вопрос: «что это, по сравнению с тем, с чем я знаком, и если я не знаком ни с чем relevant, почему я должен хотеть быть?»
Это применимо почти ко всему в программной сфере. Новый инструмент? Новый паттерн проектирования? Новая библиотека? Языковая идиома? Язык? Или, для более современных взглядов, новая модель? Новый harness? Новая опция harness? Новый паттерн использования? Дайте краткое описание того, как выглядит проект без него, чтобы передать проблему, которую решает само его существование. Затем перейдите к деталям того, как он может сравниться с другими решениями.
Может, это просто специфический способ работы моего мозга, который находит такую информацию интуитивной, а её отсутствие особенно раздражающим.
- CM30
Это, безусловно, самая большая проблема, с которой вы столкнётесь при написании туториала, прохождения видеоигры, рецепта и т.д.:
> «Читатель знает всё, что знаю я, кроме этой одной вещи»
Потому что, как говорится в статье, трудно знать, что ваша аудитория уже знает, и слишком легко «срезать углы», помогая им, забывая, сколько вещей вы довели до мышечной памяти.
Учить людей сложно, и очень легко упустить много важной информации, если не быть осторожным.
Тем не менее, у меня есть ещё один антипаттерн (и ещё один рекомендуемый паттерн проектирования), который стоит рассмотреть здесь.
Что касается антипаттерна, это когда туториал больше не работает из-за обновлений рассматриваемого предмета. Я помню, это было большой проблемой, когда я пытался изучать Angular несколько лет назад, поскольку официальный туториал был явно написан для давно устаревшей версии фреймворка, которая функционировала совсем иначе, чем текущая.
Количество раз, когда у меня были такие проблемы, слишком велико в интернете, и обычно это потому, что человек, написавший туториал, не проверял его, когда язык, фреймворк или соответствующие зависимости получали крупное обновление.
Так что, если вы пишете о теме, и вещи значительно меняются, вернитесь и проверьте свою предыдущую работу. Если можете, обновите статью, а если не можете, по крайней мере, поместите уведомление вверху, говорящее, что статья устарела и её следует пропустить.
С другой стороны, хороший паттерн, который стоит иметь в виду, — это то, что вы не не […]
- janalsncm
Я бы сказал, всё это сводится к эмпатии. Подумайте, кто ваша целевая аудитория, и пишите для наименее информированных среди них.
Это нормально быть избирательным в отношении вашей целевой аудитории. Большинство из нас всё равно пишут бесплатно, так что мы не теряем доход, не объясняя, что такое компьютер, в статье об оптимизации пропускной способности LLM. Возможно, вы пишете для других инженеров, знакомых с темой, но не с особенностями вашего проекта.
Поместите самое важное выше сгиба. Если вы привлечёте чьё-то внимание в первые 10 секунд, это даст вам ещё 30.
Добавьте визуальные элементы. Коробки и стрелки, графики, видео, где уместно.
Если вам обязательно нужно написать блуждающее повествование, поместите его в конец, а не в начало.
- linsomniac
На прошлой неделе, перейдя по ссылке с HN, я поймал себя на мысли, что техническим блогам начинает не хватать той ссылки «Перейти к рецепту», которая захватила мир фуд-блогинга (к лучшему).
- weinzierl
«Блуждающее вступление»
Не только вступление. Многие блогеры пытаются писать так, будто пишут историю, нагнетая напряжение и всё такое. В техническом письме не прячьте суть.
- zrail
Списки «делай так, а не иначе» всегда контекстны и ситуативны. Кое-что из этого имеет смысл в контексте профессионального или делового сайта, но убедитесь, что ваши цели совпадают, прежде чем следовать совету.
Если вы пишете в личном блоге, то воспринимайте всё это с той крупицей соли, которую считаете нужной. Лично для меня это примерно размер сейфа Acme, висящего над обрывом в ожидании ничего не подозревающего автора списков^h^hкойота.