Technical Writing 101 🇺🇦

2021-09-21 15:24:45 Немного о построении культуры документации на примере трёх IT-гигантов: Google, Twitter, Spotify.

В статье собраны не сколько хорошие примеры и решения проблем, сколько подборка ссылок на сами доклады, где тогдашние техписы рассказывают как они строили и/или укрепляли культуру документирования. Довольно таки познавательно, изнаночка больших компаний это как заглянуть в тетрадку к отличнику

Читать: How Google, Twitter, and Spotify built a culture of documentation Открыть/Комментировать

2021-09-15 13:39:51 Тревожные (на самом деле не очень) вести с полей JAMStack. Автор поста «RIP Jekyll (The Genesis of the Jamstack)» переживает, что Джекилл отжил свое и пора двигаться дальше. Пост немного надуманный, отчасти истеричный, да и прямых доказательств и заявлений разработчиков не особо-то и было.

Мой пойнт скорее в том, что хорошо бы научиться орудовать несколькими утилитами/языками/фреймворками/подходами, которые более-менее актуальны в вашей сфере сегодня. Остаться за бортом технологического прогресса довольно легко, и в нашей с вами области это отлично видно по количеству пользователей всяких DITA, MadCap Flare, Word и иже с ними.

Читать: RIP Jekyll (The Genesis of the Jamstack) Открыть/Комментировать

2021-09-02 16:14:51 Продолжим марафон тулз.

Часто наблюдаю, как невольные пользователи Confluence хотят причаститься к чему-то посовременнее, и, например, линтить текст в VS Code и писать в Markdown. Но как все это дело потом впихнуть в Конфу? Копипаст это скучно и к тому же утомительно.

А хочется чего-то большего, хочется git blame, хочется не кривую и скудную нативную историю изменений Confluence, а простых человеческих пуллреквестов. А может у вас даже появлялись мысли о Continuous Integration? Fear not, теперь все это можно, некий Egor Kovetskiy уже довольно давно девелопит и регулярно обновляет прекрасную тулзу под названием Mark.

Марк позволяет делать все вышеперечисленное, для этого вам просто нужно слегка сбрызнуть ваши .md файлы html-лайк метадата хэдерами и запустить миниатюрный бинарник на Go (отдельный респект).

Почитать больше можно в официальном блогпосте Use Markdown for Confluence и в соответствующем репозитории проекта. Открыть/Комментировать

2021-09-01 14:56:21 Давно мы что-то про тулзы не говорили (а ничего нового, кроме очередного yet another best-on-the-market markdown editor не выдумали). Но мы то знаем, какой редактор нужен техписателю, и нет, это не Microsoft Word, это, конечно же, VS Code.

Так вот, если вы на острие, так сказать, технологий и мейнтейните какой-то статический сайтик, вы могли заметить, что уследить за всем контентом бывает сложно, поэтому некий товарищ упростил всем нам жизнь и сделал пусть и не гейм чейнджер расширение для VS Code, но приятную мелочь, как минимум.

Front Matter — это такая себе локальная headless CMS для менеджмента ваших статических сайтиков (цитата: Hugo, Jekyll, Hexo, NextJs, Gatsby, and many more), который еще и кастомными скриптами можно расширять, лепота. Все, что дополнение умеет, можно глянуть в доках. Открыть/Комментировать

2021-08-30 17:53:33 Джулия Эванс, регулярный гость в нашем уютном бложике, но на этот раз не с своими прекрасными Зинами Для Программистов, а с перечнем так-себе-паттернов затрудняющих восприятие информации и кайфовые примеры к ним.

паттерн 1: делать устаревшие предположения об знаниях аудитории
паттерн 2: наличие противоречивых ожиданий относительно знаний читателя
паттерн 3: натянутые аналогии
паттерн 4: забавные иллюстрации на сухих объяснениях
паттерн 5: нереалистичные примеры
паттерн 6: жаргон, который ничего не значит
паттерн 7: отсутствует ключевая информация
паттерн 8: вводится слишком много концепций одновременно
паттерн 9: начинаете абстрактно
паттерн 10: неподдерживаемые ничем утверждения
паттерн 11: нет примеров
паттерн 12: объяснять «неправильный» способ сделать что-то, не говоря, что это неправильно
паттерн 13: «что» без «почему»

Даже если все выглядят до боли знакомо, сходите почитайте примеры и развернутые описания почему это плоховасто

Читать: Patterns in confusing explanations Открыть/Комментировать

2021-08-20 11:04:02 Немного апдейтов из мира стайлгайдов:

1. Google обновил часть своего стайлгайда про заголовки.
2. GitHub добавили раздел с правилами по написанию гендерно-нейтральной документации в свои гайдлайны. Открыть/Комментировать

2021-08-16 14:33:50 При сравнении продуктов, вы хотите понять, какой все же из них лучше? Тем не менее мы часто забываем оценить документацию по проекту. Проект может предлагать отличный набор функций, но в то же время у него может не быть простой в использовании документации. Это может отрицательно сказаться на процессе использования продукта и эффективности вашей команды. Автор статьи предлагает, пусть и без откровений, научиться оценивать UX документации (со стороны разработчиков).

Читать: Developer Experience: How to Define Good Documentation? Открыть/Комментировать

2021-08-04 17:38:40 Небольшой мотивационный пост, приуроченный к красивому числу подписчиков!

Спасибо, что вы есть

Мы тут не постоянно, но регулярно напоминаем себе, как важны техписы, и что нас всех стоит ценить.

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

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

И помните, it doesn’t matter how great your software is if nobody understands how or why they should use it

Читать: The uber-importance of docs Открыть/Комментировать

2021-08-02 17:46:39 Да, иногда даже на Хабре бывает полезный и читабельный контент.

Kiii~nda саксесс стори с (пере)построением базы знаний, которая действительно работает и выполняет свои задачи, а еще все это дело в Notion.

Если вам предстоит или хотя бы маячит на горизонте задача по организации обще компанейской (или хотя бы конкретного отдела) базы знаний, непременно стоит ознакомиться. Автор в относительно сжатые сроки активно покусал кактус, но все же смог, прочитайте и вы, чтобы если и кусать, то хотя бы с другой стороны.

Ждем продолжение, ну а пока, всем хорошего старта рабочей недели

Читать: Как (не) нужно строить базу знаний для проекта с нуля. Часть Первая, утопическая Открыть/Комментировать

2021-07-29 14:54:55 И мы плавно возвращаемся из отпуска! Stay tuned..накопилось много годноты. Открыть/Комментировать