Thread by @jsunderhood

Давайте под конец рабочей недели поговорим о ведении технического (и не только) блога!

- Зачем вообще вести, как начать писать;
- Насколько глубоко уходить в тех. детали в постах;
- Свой хостинг или блогоплатформа;
- Русский или английский язык.

Кидайте ссылки на свои блоги!

Расскажите, ведёте ли вы свой блог?
как начинали?
что подтолкнуло?
что для вас самое сложное?
какие плюшки вы от блога получаете?

Я пока начну и расскажу о своём блоге:
bespoyasov.ru/blog/

Начал я его вести примерно тогда же, когда начал работать. Правда, самые первые посты не сохранились, мой первый пост сейчас 2012 года.

Причин «зачем это надо» могу назвать штук 6. Сейчас пройдёмся по каждой :–)

1. Блог помогает бороться с внутренним самозванцем.

Как проверить гипотезу, что я «ничего не знаю и не умею»? Попробовать её опровергнуть.

Статья, твит, пост — всё это собирает фидбек, из которого можно составить чуть более объективную картину мира.

Бывает, правда, кажется, будто писать не о чем.
«Все обо всём уже давно написали, и смысла повторяться нет.»

Пишите всё равно!

- Не все читали то, что читали вы, кому-то это будет полезно.
- У вас могут быть детали, которых не было в других постах.
- ...

- ...Ссылайтесь на других, чтобы читатели поняли тему ещё лучше.

Главное, конечно, не плагиатить, это не круто.

В общем, не обесценивайте свои знания! То, что знаете вы, возможно, не знает кто-то другой.

2. Использовать блог, как записную книжку.

Я стараюсь конспектировать книги, которые читаю, чтобы лучше уловить суть.

Если мне потом понадобится вернуться к книжке, то я сперва возвращаюсь к конспекту. Если там есть то, что я искал — отлично...

...Если нет, то это повод перечитать книгу и дополнить конспект.

Потом я подумал, чего б не делать конспекты хороших книг публичными? Вдруг кому-то ещё зайдут.

Один из последних конспектов по Петцольду — зашёл 😃
bespoyasov.ru/blog/code-the-…

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

Например, вот пост-сниппет об обработке ошибок:
bespoyasov.ru/blog/error-han…

Или инструкция к описанию багов:
bespoyasov.ru/blog/cant-repr…

Удобно, что оно доступно глобально без аутентификации.

3. Стандартный ответ на вопрос.

Стабильно выкладывать посты я начал после того, как пришёл преподавать в Нетологию.

Я проверял домашки и вёл дипломы, из-за чего мне приходилось часто отвечать на одинаковые вопросы.

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

О шаблонах и инсайдах я потом написал подробный пост 😃
bespoyasov.ru/blog/one-and-a…

Позже я стал отвечать на вопросы людей из почты и сотрудников. Когда я заметил, что они тоже повторяются, начал постить в блог ответы на них.

(Отчасти поэтому, я часто скидываю ссылки на свой блог на этой неделе — в постах всё расписано подробнее, чем можно рассказать в твите.)

Из таких стандартных ответов могу вот привести:

- Как описывать баги
bespoyasov.ru/blog/cant-repr…

- О документации
bespoyasov.ru/blog/documenta…

- Копипаста в коде
- bespoyasov.ru/blog/copy-past…

4. Это работает почти как Гитхаб!

Блог часто приносит мне хорошие офферы и освобождает меня от собесов ¯\_(ツ)_/¯

Я сам офигел, когда такое в первый раз произошло 😃

Как там сейчас модно говорить — личный бренд? Это вот оно как раз.

5. Это хороший тренажёр для формулировки мыслей.

Я заметил, что после какого-то времени ведения блога, у меня получается на письме хорошо формулировать мысли и задачи.

С задачами вообще огонь, потому что хорошая формулировка проблемы — половина решения.

Это, правда, почти не повлияло на мою устную речь. Этот навык надо, видимо, отдельно развивать 😅

6. Поле для дискуссий.

Вообще, я сейчас стараюсь так не делать, но вначале, если меня что-то возмущало, я мог написать статью об этом.

Например, вот:
bespoyasov.ru/blog/how-to-in…

Но сейчас мне это кажется треш-толком, поэтому реактивных на что-то постов стараюсь не писать.

А сейчас поговорим о том, как вытащить из себя статью.

- Что делать, если я постоянно отвлекаюсь?
- Как и когда редактировать?
- Насколько уходить в детали, если есть примеры кода?

Итак, у меня есть идея для статьи. Я сажусь её писать, и...

То чаю захотелось, то в Твитере что-то интересное пишут, то пишу, но получается нудно, скучно, и вообще, писательство — не моё, ну его нафиг.

Знакомо.

Есть три принципа, которыми я пользуюсь, чтобы избегать ступора, прокрастинации и разочарования:

- «Есть слона по частям»
- «Ну блин короче...»
- «Редактировать — отдельно»

Разберём каждый.

Я замечал за собой, что прокрастинирую я те задачи, которые кажутся большими, объёмными и _непонятными_.

Новый пост — это та ещё непонятная задача. Сами посудите:

- с чего начать?
- как сформулировать проблему?
- какая аудитория?
- что читатели должны знать перед прочтением?

Все эти вопросы так или иначе возникают при написании статьи.

Просто мы можем не отдавать себе отчёт, что они есть. Но фоном мы всё равно будем пытаться на них ответить ¯\_(ツ)_/¯

Первый принцип «Есть слона по частям» старается разбить большую непонятную задачу на маленькие куски.

Такие маленькие задачи можно решить по одной за раз. Ну типа,

- «определиться с проблемой»;
- «определить уровень знаний перед прочтением»;
- и т. д.

Этот же принцип я применяю при собственно написании текста статьи.

Я не пишу сразу огромную портянку на 40 тысяч символов — это сложно, выматывает и вообще.

Сперва я намечаю структуру заголовков — это помогает составить «карту», по которой я потом буду идти.

Причём
- сперва структура состоит только из верхних заголовков,
- потом я уточняю каждый раздел подзаголовками,
- потом в каждый подраздел накидываю тезисов.

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

И тут наступает проблема «белого листа» — С Ч Е Г О Н А Ч А Т Ь ? 😃

Используйте второй принцип: «ну блин короче».

Начните ваш текст поста с «Ну, блин, короче...» и дальше пишите всё, что считаете нужным.

Пишите просто сплошняком, без абзацев, без разбиения на предложения. Строчите из буквомёта, пока идёт.

Не беспокойтесь, вы это отредактируете, но потом:
Третий принцип «Редактировать — отдельно».

Старайтесь разделять сессии написания и редактирования.

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

Всё это встаёт в прямое противоречие с «написанием».

Можно сравнить написание с брейм-штормом, а редактирование — с анализом результатов.

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

Как так? Неужели поток мыслей закончился? У меня что, больше не о чем написать? Всего лишь 2 абзаца сделано.

Всё нормально. Вероятно, вы устали. Возьмите перерыв.

Важно: во время перерыва я не смотрю на то, что написал. Вообще.

Если я отдыхаю от текста, то не вспоминаю о нём до следующего подхода. Даю, так сказать, нейронам остыть.

В следующий раз, когда я сяду за текст, я буду отдохнувшим от него (что позволит найти ошибки и нелогичное повествование).

А ещё такая перезагрузка, вероятно, даст время дефолт-системе мозга поработать за меня:
ru.wikipedia.org/wiki/Сеть_пасс…

Забавно, но именно во время мытья посуды или прогулки я придумываю хорошие доводы и сравнения для своих статей ¯\_(ツ)_/¯

Хорошо, вот за несколько подходов мы наполнили структуру из заголовков каким-то текстом.

Там нет абзацев, иногда нелогичные переходы, предложения не согласованы, вот это всё.

Что дальше? Дальше можно начать редактировать.

Я обычно сперва проверяю логику повествования:

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

На этом этапе можно переделывать структуру всего текста, как захочется, потому что сил потрачено ещё не очень много.

Можно двигать разделы, абзацы, заголовки, куда угодно.

Это пока что не булка, а тесто — месить его вполне нормально.

Когда с логикой всё хорошо, можно углубляться в сам текст:

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

После того, как текст становится монолитом, где ни убрать, ни добавить, можно приступать к пунктуации, орфографии и грамматике.

Если есть роскошь дать кому-то почитать — обязательно дайте.

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

Днём поговорим о том, что выбрать:

- свой хостинг или чью-то платформу;
- русский или английский язык.

Продолжим 🙂
Давайте ещё один опрос!

Self-hosted блог или чья-то платформа?

Я топлю и всегда топил за селф-хост.

У платформ я вижу только одно преимущество — можно сразу писать на какую-то аудиторию.

Всё, дальше только минусы 😃

- Контент — не мой;
- Площадка может на мне наживаться и вообще вести себя по-скотски (привет, Медиум!);
- Если площадка большая — пост теряется среди тысяч других;
- Не всегда удобно писать и публиковать.

Я писал немного на newline и сейчас пробую dev.to в рамках эксперимента, чтобы выйти на зарубежную аудиторию, посмотреть чё-как, почву прощупать.

Но уже сейчас понимаю, что мне, вероятно, придётся делать английскую версию сайта :–/

В селф-хосте мне нравится, что контент всегда остаётся у меня и в одном месте.

Я могу переехать со своими заметками куда захочу, устроить процесс публикации, как мне удобно:
- bespoyasov.ru/blog/new-site-…

— Но для селф-хоста нужен дизайн!

Не-а 😃
Можно наверстать сайт на чистом HTML без стилей. Если есть, что написать, это будут читать:

- ariarzer.dev

— Но для селф-хоста нужен домен и хостинг, и TLS, и деньги!

Да, но не очень много:

- HTTPS можно подключить через letsencrypt.org
- Цена на домен зависит от зоны (.ru — дешёвые)

— Но селф-хост надо промоутить!

Сарафанное радио работает не хуже, чем блого-платформы.

(Говорю по опыту:
- front-not-pain.bespoyasov.ru)

Кстати, насчёт сарафанного радио.

У Веб-стандартов недавно появился список с инди-блогами о фронтенде ;–)

- github.com/web-standards-…

— Но что, если я не буду писать?

Всегда можно сделать архив с заметками и опубликовать их в тех же gist на Гитхабе, если вы поймёте, что держать свой блог невыгодно или не хочется.

— Но я не хочу кодить, я хочу просто писать!

Если не хочется _много_ кодить, то можно посмотреть на генераторы типа 11ty.dev или чего-то похожего.

Если кодить не хочется _совсем_, то да, наверное, селф-хост не подойдёт :–)

Окей, а что с языком? 😃
На каком языке писать: русском или английском.

Мне гораздо проще писать на русском и потом переводить на английский ¯\_(ツ)_/¯

Я понимаю, что это контрпродуктивно, но вот так :–/

Контрпродуктивно, потому что хороший пост с английского и так переведут на русский, а я делаю двойную работу 😃

Ну, пока у меня не получается сломать свои привычные шаблоны.

Англоязычная аудитория по умолчанию шире. Охват будет больше, фидбека будет тоже больше.

Если вы заводите трактор, то понятно, что это вообще единственная опция 😃

Чтобы писать на английском, я использую:

- deepl.com/translator — для перевода, умеет в идиомы, понимает контекст (лучше Гугла 😃)

- app.grammarly.com — для проверки грамматики и орфографии, помогает расставлять запятые (в английском не понятные для меня правила 😅)

Если вы пишете на платформу, где используется Markdown, то вот читщит по нему:

- github.com/adam-p/markdow…

(У картинок сначала — квадратные, потом круглые скобки 😅)

В общем, не повторяйте моих ошибок, пишите сразу на английском 😃

Отправляюсь работать.

После поговорим об RSS (надо / не надо) и как вставлять примеры кода (нужна ли подсветка, сколько кода — слишком много кода).

Продолжим!

RSS — надо или нет. До сих пор считаю, что ничего лучше для подписки на блог не придумали 😃

А когда появились «умные» ленты, без RSS стало вообще нереально ничего читать.

Не у всех платформ RSS есть, и в селф-хосте добавить его тоже бывает сложно.

Мне вот пришлось писать собственный скрипт для генерации ленты:
- bespoyasov.ru/blog/new-site-…
- github.com/bespoyasov/www…

Но RSS для меня — единственное место, где блоги читать _удобно_.

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

Соц. сети — возможно, но там нужно следить самостоятельно, не пропустил ли чего. Это неудобно.

Поэтому для меня ответ однозначный — да, RSS нужен.

*Старческое кряхтение.*

А теперь о примерах кода 😃

Вот мы пишем статью о какой-то технологии или случае из разработки. Там будет код.

Как его правильно оформить?

Нам же одновременно надо решить почти противоречащие задачи:

- Кода должно быть не слишком много, чтобы было проще читать.
- Но кода должно быть достаточно много, чтобы передать контекст проблемы.

- Код должен быть не слишком сложен и специфичен, чтобы пример был проще для понимания.
- Но код должен быть достаточно специфичен, чтобы не быть примером а-ля `2 x 2 = 4`.

- Как быть с примерами, которые нельзя разделить на более мелкие?
- Добавлять ли слишком мелкие примеры?

Начнём с простого.
— Добавлять ли простые и маленькие примеры?

Да, лучше добавить. Это как в кино, лучше показать, чем рассказать.

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

Но при этом объяснения к коду тоже стоит привести.

— Писать объяснения до примера, после или внутри?

Расположение не имеет значения, но последовательность — имеет. Лучше выбрать для себя правило и следовать ему на протяжении всего поста.

Вопреки расхожему мнению, я считаю, что пояснения внутри кода в виде комментариев — хорошо.

Хорошо, потому что объяснение находится прямо в том месте, которое объясняет.

Лучше написать комментарий перед строкой с объяснением, чем потом писать «А на 6-й строке мы делаем бла-бла».

Мне ещё кажется, это более привычно для читателей, потому что они сами видят комментарии именно в таком виде на работе.

— Как выбрать, какой код добавлять в статью?

Я стараюсь добавлять код, который относится _непосредственно_ к теме статьи.

Читаю заголовок или подзаголовок, задаю себе вопрос: «Этот код относится к теме?»

Да — добавлю, нет — в топку его, иначе будет шуметь.

— Что делать с примерами, которые не делятся?

В первую очередь подумать, можно ли это отрефакторить.

Затем подумать, как бы вы группировали такой код отступами в редакторе. Где добавите пустые строки — там можно выделить отдельный кусок.

Теперь самое сложное:

— Как выбрать, какой именно код и сколько код приводить в примерах?

Откусывайте от кода маленькие кусочки до тех пор, пока откусить будет больше нечего.

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

Отдохните и проверьте, понятна ли идея за примером.

Если деталей наоборот не хватает, добавляйте по одной до тех пор, пока идея примера не станет понятной.

Акцентируйте внимание на развитии примера сквозь статью.

Давайте на примере моего поста о DI:
- bespoyasov.ru/blog/di-ts-in-…

Показываем предпосылку к идее на простом примере кода:

(Зависимости — это как аргументы.)

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

(Кроме аргументов мы используем глобальный объект — зависим от него.)

Приводим читателей за руку в собственно идею:

(Такие зависимости тоже можно передавать явно.

Обратите внимание, что внутренности функции спрятаны за многоточием, они здесь не важны.)

Этот же кусок кода мы дальше используем, как опорную точку для развития идеи:

(Важно описать поведение, не важно, какой именно объект использовать.)

Так, от простого и _знакомого читателям_ кода мы переходим к новым для них концепциям.

Знакомый код даёт ощущение твёрдой почвы, знания базы.

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

Ну и предлагаю сегодня закончить пораньше — пятница всё-таки 😃