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

Тогда же я записала свой видео-обзор на эту IDE. Я никогда не думала, что монтаж — простое дело и можно справиться за пару часов. Но прошло полтора месяца 🥲 поэтому:


⭐️ Текстовый самап ⭐️

Writerside сразу настроен на работу с docs-as-code. Более того, там есть встроенный SSG и теперь не надо выбирать между Hugo и Jekyll — можно просто задеплоить проект на, например, GitHub Pages (эх, в видео это тоже разобрали).

Надо ли бежать с уже привычных VS Code или Idea — скорее нет.
Надо ли пробовать работать в новой IDE — точно да. Особенно, если у вас ещё не выстроены отношения с какими-то конкретными инструментами.

➕ поддержка плагинов
➕ коробочный генератор в html
➕ терминал и прочие прелести IDE
➕ шаблоны проектов

➖ что-то новое, к чему надо привыкать


Используете ли вообще IDE для работы с документацией?


—
Учитывайте лицензионные ограничения

Уииии👀

Спасибо всем, кто пришёл к нам в офис — была рада видеть столько и настолько заинтересованных людей ✨

📺 Запись 📺

На этот год сезон закрыт, спасибо всем спикерам, огранизаторам, волонтёрам и просто всем-всем-всем ❤️

а я уже в аэропорту 37й раз за год

Следите за анонсами 😏

Почти новогодний подарок 😍

Мы открыли наём

В описании только про внешние доки, но рассматриваем и на внутренние проекты — ищем сразу несколько человек 🎼

⭐️ позиция младшего техписателя — можно без опыта вообще;
⭐️ желательно в Москве, но рассматриваем и другие города, и удалёнку;
⭐️ четыре этапа отбора: резюме -> общение с рекрутером -> тестовое -> техсобес.

Откликаться на Ozon Job или HH 👨‍🎤

#вакансия

У меня есть одна суперспособность — не попадать на фото с мероприятий.

Поэтому когда выложили фото с Techdoc Meetup 3 я первым делом даже не подумала себя на них искать.

А потом вспомнила, что была ведущей и, наверное, хоть на паре фотографий окажусь 🐸

Если у вас такая же суперспособность — приходите спикером на следующие митапы 😉

Получили уже 100 откликов на вакансию 😲

Если вы пока только готовите своё резюме, проверьте эти штуки:

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


Однородность текста
Если начали описывать свой прошлый опыт списком задач — так и продолжайте. Если стали выделять курсивом полученные метрики — так и продолжайте. Следите, чтобы все прошлые места работы считывались по шаблону, а не выглядели лоскутным одеялом. Учитывая, что вакансии у нас о тексте — резюме тоже показывает ваши навыки.

Уникальность сопроводительного письма
Если вы написали сопроводительное письмо и оно теоретически подходит для абсолютно любой команды и компании — это плохое письмо. Напишите почему именно здесь и именно вы хотели бы работать. Мы всё равно спросим это на собеседовании 😎

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


Хоть какой-то отклик лучше, чем неотправленный вовсе
Поэтому тут тоже важно не потратить всё время отбора на выдраивание резюме, а отправить хоть что-то относительно адекватное. Лучше, конечно, отправлять что-то сильное и хорошее, но если у вас ещё нет опыта — значит, первая цель не получить работу, а научиться составлять резюме 👨‍💻

В первом «Пиши, сокращай» так рьяно сокращали, что в новом пришлось объяснять как писать 🤩

И вот в этом основная разница — в новом издании лучше видно отличия между языком самой книги и инфостилем

Ещё в самое сердечко упоминание техписателей как целевой аудитории этой книги ❤️

Оформлено красивенько, полезных мест вон сколько и чаще в начале страницы

➖ Всё ещё нет буквы Ё
➖ Мягкая обложка моментально помялась

Если не читали первое издание — начните со второго, оно актуальнее и авторы поработали с обратной связью, чтобы объяснить всё недопонятое

А то даже сегодня в команде поднимали тему категоричности Ильяхова и его любви всё сокращать

Худшие книги года 📚

1. Нетревожные отношения с едой (и с собой)
Половина книги о конкретных кейсах: «ем много сладкого» и «ем мало овощей». Но я не ем много сладкого и не ем мало овощей.
А в целом — стандартная мысль, что не надо на еду злиться.
Полезная мысль: бывает физический и эмоциональный голод и стоит научиться их различать.

2. Сказать жизни «Да!»: психолог в концлагере
История Виктора Франкла в концлагере, по сути — те же идеи, что у Эдит Евы Эгер в Выборе. Сильная и важная книга, думаю, если бы прочитала до Выбора — мне бы больше понравилось. Но в такой последовательности чтения даже разочаровалась.

3. Гром: Трудное детство. Восход Анубиса
Комикс-вступление к фильму. Зачем его в отдельное произведение — не знаю. Наверное, просто не поняла концепт.

4. Мадам Таро
Описание настолько же заинтриговало и понравилось, насколько в итоге книга разочаровала. Надеюсь, по ней снимут дораму, потому что настолько странный и беспощадный сюжет не должен остаться только на бумаге.

С другой стороны — если я дочитала эти книги, то они не так уж и плохи 🎈

Да, это был байт 🫥

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

Безоценочный — это когда мы если и говорим «хороший», «плохой», то обязательно приводим объективные критерии.

Я опустила историю, что всем прочитанным книгам ставлю оценку от 1 до 5. Это субъективная оценка, у неё нет чётких критериев. И это значит, что мою оценку книг вообще нельзя брать за какую-то метрику или ориентир. Это значит только, что если вы спросите «Кать, как тебе вот эта книга?» — я отвечу «ну, на троечку, не очень понравилась». Но саму книгу-то это не характеризует.

Поэтому если вам надо сказать в статье / блоге / другом публичном пространстве, что что-то какое-то — лучше опишите факты, а читатель уже сам решит, какую оценку этому чему-то поставить 🐹

#тексты

📚 38 книг за год
оказалось в моих руках

Из них дочитала 30, понравилось — 23, а особенно выделить хочу 4

⭐️ Номер два, Давид Фонкинос — о парне, которого не взяли на роль Гарри Поттера.
⭐️ Вы найдёте это в библиотеке, Митико Аояма — истории разных людей, связанных одной библиотекой.
⭐️ Замок из стекла, Джанетт Уоллс — о девочке, которая оказалась ментально старше своих родителей.
⭐️ Will, Уилл Смит, Марк Мэнсон — история успеха, работы и череды решений, которые сделали из простого парня самого высокооплачиваемого актёра Голливуда.

Читали? 🦩

С Новым 🎄
Счастья всем ❤️

Один из главных боссов на пути к каким-то целям и хотелкам — перфекционизм.
Поэтому я не старалась сделать идеально, хотела просто сделать как получится по адекватному соотношению ресурсов и результата ❤️

Правда это было в октябре 😅 но стоило заправиться салатиками и выспаться в понедельник и вот он — первый взгляд на новую IDE для техписателей от JetBrains ❤️

😉 Обзор Writerside IDE

*Это не инструкция, не гайд, не best practices, а именно первый взгляд на эту IDE

Если досмотрели до конца и вам бы хотелось больше такого формата — дайте знать 🐈

Выхожу из спячки постом на бусти. Пока что весь контент там бесплатный, платные только консультации.

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

Допускаю, что позже какие-то особо трудоёмкие материалы уйдут в платную зону 🐥

💫 Начнём рабочий год с простого и полезного напоминания

Техническая документация — это документы, созданные для объяснения технических аспектов продукта или услуги. Это может быть что угодно — от простых руководств пользователя, до комплексных спецификаций и отчётов.

Техническому писателю важно понимать технические основы — иначе он будет просто писателем, а это уже другая профессия. Речь именно о базовых концептах, потому что быть специалистом во всех технологиях, о которых приходится писать, невозможно. Важнее уметь собрать информацию и грамотно её изложить.


Самые-самые базовые книги и ресурсы

⭐ The Product is Docs: Writing Technical Documentation in a Product Development Group — базовая база о продуктовой доке.
⭐ Writing in the Technical Fields: A Practical Guide — практические рекомендации по этапам работы с докой.
⭐ Technical Writing For Dummies — особенно хороша для тех, кто ещё не в профессии, но очень хотелось бы.
⭐ Пиши, сокращай 2025 — о работе с текстом, вообще любым.

⭐ I'd Rather Be Writing – блог с полезными статьями и уроками по технической документации.
⭐ TechWhirl – сообщество технических писателей с форумами, статьями и руководствами.
⭐ Write the Docs – сообщество профессионалов, организующих конференции и встречи.

#techdoc

Новый год — новые задачи 🎄
но у каждой из них должны быть:

✏️ такое описание, что даже человек из другой команды или после трёхлетнего отпуска понимает, что и где надо делать;

✏️ если задача больше, чем на один подход к ней, то обязательно должна быть декомпозиция на подзадачи, каждая из которых занимает не больше одного рабочего дня;

✏️ адекватные сроки для каждого этапа работы, зафиксированные в задачах и одобреные заказчиком;

✏️ своевременная обратная связь от заказчика или от коллег, если в роли заказчика — вы сами.


Когда сами создаёте задачу, всегда проверяйте её по формуле «что-где-когда»: что надо сделать; в какой системе или статье; когда нужен результат.

Хотя с «когда» всегда тонкая материя — если дата пальцем в небо и просто потому что так захотелось, то скорее всего реальная дата «никогда» 🐻

#mngr

Один из важнейших навыков для техписа — разбираться в больших объёмах новой информации и структурировать её для читателя 🐸


Как это сделать:

1. Определить цель — если понять зачем, весь процесс становится прозрачнее и легче.

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

3. Использовать форматирование — заголовки, плашки, списки, таблицы — ваши верные спутники в мире текстов, особенно технических.

4. Выделить важное — но только действительно важное, иначе можно выделить всю документацию и надо будет выделять из выделения.

5. Соблюдать консистентность — проверяйте, что все заголовки, списки, глаголы, термины и всё остально выдержано в едином стиле, принятом в вашей компании.


Помните, что структурированная и чёткая подача информации значительно упрощает восприятие и относится не только к конкретной статье, но и ко всему представлению бренда 🐸

#techdoc

У кого уже дёргается глаз от словосочетания «Эффективные коммуникации» — ставьте 😨

Из необходимости собирать много информации и укладывать её особенными образами, вытекает навык общения со смежниками, командой и заказчиками. И с каждым из них надо говорить понятными им терминами, поэтому жаргонизмы и сокращения надо либо объяснять, либо избегать. Есть у меня история, когда из-за одного слова пришлось разворачивать месяц работы 🫠

У кого глаз дёргается и на «активное слушание» — с вас два лайка 😱 пытайтесь стать на сторону говорящего, понять его мотивы и контекст. Обычно люди не специально в чём-то не сходятся — попытайтесь понять оппонента.

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

И на десерт — сообщайте всем сторонам о статусах. Лучше всего это делать в самой задаче комментарием. Поставьте себе напоминание раз в неделю и ходите отписывайтесь в задачах, что сделали, какие были сложности, что будете делать. Даже если ничего не сделали — так и напишите. Иначе вас придут долбить в личку, вы будете стрессовать и результат будет «на отвали» 🫣 Не успели? Проанализируйте и честно напишите в статусах «не успел».


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

#mngr

Сегодня коротко ловушках, которые ждут нас в техническом документировании.

1. Запутанный язык. Сложно не значит круто. Простота и ясность — наши лучшие друзья.

2. Несоответствие стиля. Если документ выглядит как пазл из разных кусочков, это плохо. Единый стиль — залог понятности.

3. Непроверенные факты. Ошибки в данных могут стоить дорого (буквально, спросите у юристов). Проверяйте, проверяйте и ещё раз проверяйте!

4. Игнорирование фидбека. Мы не всегда идеальны и это нормально. Слушайте коллег и пользователей.


Коротко: держите тексты простыми, стиль — единым, факты — проверенными и уши — открытыми для советов 👋

#techdoc

Устаревшая документация может быть не просто бесполезной, но и вредной. Поэтому одна из наших ключевых задач — регулярное обновление документации. Это как в саду: чтобы документы оставались свежими и полезными, их нужно поливать новой информацией 🌱


Но как сделать это эффективно? Есть три базовых варианта:

⏳ Создайте план или график регулярных обновлений. Это поможет не забыть про необходимость пересмотра документов.

💌 Следите за изменениями в продукте или услуге, о которых вы пишете. Подпишитесь на рассылки, договоритесь о регулярных встречах, ходите на синки.

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


Высший пилотаж — автоматизация актуализации. Но тут уже сильно завязано на конкретно ваши инструменты и процессы 🐌

#techdoc