Ещё раз про KPI
для техписов и в принципе

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

Если оценка сотрудников сводится только к количеству проделанной работы — теряется понимание а зачем всё это вообще надо. Поэтому можно использовать KPI как дополнительный показатель, но основывать на нём работу направления — бессмысленно.

Используйте SMART, обращайте внимание на то, какие продуктовые метрики надо улучшать, думайте вместе с коллегами над решением. Здесь могла быть интеграция курса по метрикам 🐹

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

Ваша задача, как сотрудника любого уровня, понимать глобальную цель. Как директора, кстати, тем более 🥺

🌟 #вопросы #techdoc

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


🌟 По каким принципам можно формировать разделы в пользовательской документации?

Глобально есть два подхода: описательный и сценарный.

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

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

Лично я — сторонник сценарных документаций, аргументы можно послушать в докладе Юры Никулина и у меня на митапе Cloud.ru. В таком подходе верхними уровнями будут ключевые точки взаимодействия пользователя с системой: получение доступа, настройка окружения, деплой, закрытие релиза; регистрация, поиск товара, заказ, возврат.

Но! 🌟

Если пользователь говорит, что ему что-то не нравится — стоит исследовать почему. Поэтому просто сказать «пишите от процессов и будет у вас счастливый читатель» — не правильно. Ваш читатель не всегда знает, как решить свою проблему и как ему будет действительно удобно. Но вы в силах пообщаться с ним и найти лучшее решение для вашей конкретной ситуации..


🌟 Как определить оптимальную длину статьи?

Если это веб-ресурс — около 2-2,5 экранов вашего читателя.

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

И, пожалуйста, не забывайте, что мы пишем документацию не ради количества знаков с пробелами, а чтобы помочь пользователю. Поэтому искусственно наращивать объёмы не стоит. Посмотреть, с чем можно объединить или на что можно разбить — да; запретить выкатку статьи меньше 2 экранов — нет.

Techdoc Meetup 3 😎

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


🏳️ Нужна ваша помощь

1. Ищем спикера — можно присылать мне в личные сообщения идею доклада на 20-25 минут. Необязательно что-то серьёзное об организации знаний или фреймворках документирования — если у вас есть пачка историй из жизни техписа, видение музыкальных паттернов при написании текста или что-то другое ненавязчиво-праздничное — приходите 🚀

2. Ищем вопросы для круглого стола — их можно в комментарии к посту. Если есть пожелания по участникам круглого стола — туда же, в комментарии ⚡️


Точную дату и место сообщим чуть позже, следите за анонсами в сообществах техписателей 🎤

#анонс


▶️ Записи прошлых Techdoc Meetup
0. Декабрь 2022
1. Июнь 2023
2. Сентябрь 2023

#вопросы #techdoc

🐸 В идеальном мире код документирует себя сам, а структура документации показывает CJM.

Но пока идеальный мир не наступил и иногда случаются инструкции к инструкциям. Это даже не всегда плохо.


Как познакомить сотрудников со структурой Базы знаний в Confluence?

1. Встроить это знакомство в онбординг — нарисовать схемку «это — здесь, то — там», добавить обязательный квест «найди X». Так сотрудники познакомятся с внутренней Базой и научатся пользоваться Confluence.

2. Только если База знаний достаточно статична, её структура не будет обновляться и в целом База уже пробивается на камне — можно записать видео. Иначе неактуальное видео будет путать сотрудников, либо его надо будет переснимать каждые 2-3 месяца. Ещё стоит учесть, что видео может стать камнем, тянущем пересмотр структуры ко дну — поэтому лучше сначала провести исследование, аудит и актуализацию, а потом уже записывать обучающий ролик 🐸

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

Надо будет доделать-таки одно видео и рассказать о прошедшем буткемпе. Ну и ещё миллион тем о текстах, техписательстве и жизни в корпорации 🦢

Но чуть-чуть позже, сейчас мне нужен отдых 🍄

Книга никак не связана с профессиональной деятельностью и не будет продаваться

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

сегодня слушала прогоны — доклады в этот раз глобальнее просто разговоров о текстах, поэтому очень рекомендую подключиться к обсуждению в реальном времени 💻

Ноябрь — самый серый и непонятный месяц в моём восприятии года. Особенно в московских широтах 😷

Поэтому второй год мы с командой выезжаем в Сочи между распродажами 😎

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

Основная сложность в этих поездках — найти удобное жильё 😐 а всё остальное уже легко делается на месте классной командой 🤗

Организация митапов и выездов для техписателей под ключ, недорого 🫥

Чуть больше месяца назад 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

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