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

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

Правда это было в октябре 😅 но стоило заправиться салатиками и выспаться в понедельник и вот он — первый взгляд на новую 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

Помните, мы нанимали в декабре?

У нас есть ещё одна бонусная вакансия 😍

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

На хх выкладывать не будем, пройдёмся по уже накопленной базе кандидатов. Поэтому если вы не откликались раньше — присылайте свои резюме мне в личку @ushkatia 😼

UPD
Пока всё, отсматриваем резюме, спасибо за отклики.
Если вы откликнулись, но вам не напишут до 5 февраля, вы всё равно останетесь в нашей базе кандидатов и в следующую вакансию мы снова на вас обратим внимание.

Боги, храните людей, которые не ждут два года пока ты их допинаешь, а сами приходят обновлять статусы ❤️

Agile-дока 🍊

Agile — это не просто способ разработки ПО, это философия, подчеркивающая быстроту, гибкость и адаптивность. А как же быть с документацией, которая требует точности и внимания к деталям? Ключевое слово здесь — «синхронизация».

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

И нельзя забывать о коммуникации. В Agile коммуникации — часть документации. Регулярные встречи, совместная работа и обратная связь помогают держать документацию up-to-date 🚲

#mngr

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

Поэтому в такой доке должны быть такие вещи:

⭐️ описание функций и методов;
⭐️ примеры кода для быстрого старта;
⭐️ инструкции по интеграции.

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

Из-за этого иногда кажется, что документация API — это что-то запредельно сложное и писать её могут только старшие специалисты. Категорически не соглашусь ☠️

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

#techdoc

Давайте про виды картиночек в доке?


📌 Диаграммы, гистограммы и прочие графики. Используйте гистограммы и круговые диаграммы, чтобы наглядно демонстрировать статистические данные. Это помогает быстро оценить объемы, соотношения и тенденции.

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

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

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


Но! Визуализация должна упрощать понимание, а не усложнять. Каждый элемент должен быть четким, информативным и соответствовать контексту. Тут тоже главное не ударяться в крайность и не превращать документацию в комикс.

Хотяяяя всё зависит от вашей ЦА ❤️

#techdoc

🌟 Лингвошутка 🌟

Занимаюсь китайским
Надо было перевести предложение
«После долгого рабочего дня у меня часто болит голова»

Выбрала не тот иероглиф
Получилось примерное такое:
«После долгого рабочего дня моя голова плещется ручейком»

В принципе, смысл не пострадал.

🐈 Новости 🐈

В этом году лидовья часть Ozon-техписов читает курс в Иннополисе 😮

На первой неделе разобрались в основах, обсудили инструменты 🐈

А остальной командой начинаем готовиться к сезону конференций — анонс первой уже совсем скоро 💻

#lifestyle