Всем привет!

Сегодня вечером в 18:00 по московскому времени пройдёт бесплатный митап для технических писателей, организованный Ozon Tech.

О чем пойдёт речь?

► Маргарита Жданова из X5 Tech поделится опытом внедрения docs-as-code в своей команде.
► Теодора Малевинская из Тинькофф расскажет о том, что документация — не панацея, или как писать не для галочки.
► Мария Смирнова из Ozon представит 10 принципов хорошего перевода.

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

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

1️⃣ Определяем цель
Зачем нужен этот текст? Это очень важный вопрос, от ответа на него зависит не только содержание и форма, но и место текста в общей иерархии статей.
Например, решение точечной проблемы можно описать кратко и ёмко и поместить в Ответы на частые вопросы (FAQ).

2️⃣ Определяем целевую аудиторию
Для кого мы пишем? Кто наши читатели? Это простые пользователи или продвинутые администраторы? В зависимости от ответа мы определим, насколько подробно необходимо расписывать действия.
Например, при описании API (программного интерфейса) не нужно объяснять, что такое API и как он работает. Как правило, люди, использующие API, уже обладают определенными знаниями. А если мы создаем продукт для, например, официантов, мы расписывает действия подробно: что запустить, куда нажать, какие поля заполнить.

3️⃣ Создаем текст
Пользовательскую документацию можно писать по спецификации, со слов разработчика, тестировщика или другого носителя знаний, либо повторить путь пользователя и записывать свои действия.
Стандартное содержание статьи примерно такое:
Заголовок - Введение (описание) - Что нужно знать предварительно - Как попасть - Как решать задачи.
Созданию текста посвятим отдельный пост.

4️⃣ Проверяем текст
Когда текст готов, его может посмотреть другой технический писатель, редактор, а если текст вы пишете по задаче - автор задачи, заказчик документации. Ревьюэр предлагает правки, а заказчик решает, всё ли сделано верно или лучше доработать.

❗️Обратите внимание, что в каждой компании выбирают свой порядок ревью. Где-то сначала смотрят заказчики, а потом "выглаживают" другие техписатели или редакторы. Решение принимается в зависимости от сложности продукта, погруженности техписателей, иногда - после проб и ошибок. (тут тоже ждите отдельный пост)

5️⃣ Публикуем и продвигаем
После того, как заказчик утвердил текст, его передают пользователям: публикуют, собирают pdf или каким-то другим способом.
Часто этого бывает мало. Необходимо рассказать об обновлении своим читателям, например, в рассылках. И этот процесс тоже заслуживает отдельного поста.

Получился длиннотекст) Спасибо, что дочитали☺️
А теперь вопрос к опытным техписателям: как у вас организован процесс ревью?
Если заказчик смотрит первым, поставьте в комментариях "1".
Если заказчик смотрит последним, поставьте "2".
Посмотрим, кого больше)

#вопросвлоб
Всем привет!
Продолжаем знакомиться с вопросами, которые вам могут задать на собеседовании.

Какой должна быть качественная документация?

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

1️⃣ Актуальная
Все доработки и исправления должны быть описаны вовремя.

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

2️⃣ Полная
Должны быть описаны все возможности продукта.

Проблема, если документация неполная:
Разработчик зашел в продукт и увидел раздел в меню: интеграции с сервисами Сбера. Это то, что ему нужно, но он не нашел в документации, как выполнить программную интеграцию, потому что из методов API вы описали только авторизацию.

3️⃣ Доступная
Нужную информацию пользователь должен получать быстро и на понятном ему языке.

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

Это три основных признака, но вы можете дополнить критериями из своей практики.

Всем привет!

Задумывались ли вы, что документация может принимать самые разные формы? Мы привыкли, что документация — это текст, в который можно добавить картинки, диаграммы и другие визуальные штуки, чтобы упростить восприятие. А что, если текст — это основа, но не всё?

Документация — это шире :)

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

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

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

Что же, надо всё бросать и бежать осваивать новые форматы? Конечно, нет. Наша задача — сделать так, чтобы все поняли, как работает продукт. А способы донесения информации могут быть разными. Если нынешний или будущий работодатель спросит у вас, как можно освежить документацию, вы всегда можете предложить попробовать другой формат. Не бойтесь экспериментировать, ведь именно через эксперименты открывается что-то новое.

Расскажите, как вы относитесь к форматам документации, отличным от текста?

Технический писатель - самая удобная точка входа в IT. Но это вовсе не значит, что в IT вы можете быть только техписателями.

Сегодня, 19 июня, в 17-00 по Москве слушайте подкаст Карьерный разговор с участием гуру техписательства Николая Волынкина. Вместе с Александрой Камзеевой и Андреем Бураковым они обсудят документацию и смежную сферу - аналитику, расскажут, что же объединяет техписателей и аналитиков, какие между ними различия и как эти специалисты могут друг другу помогать.

Подключайтесь!

#вопросвлоб
Продолжаем рассматривать вопросы на собеседовании. Ранее мы рассмотрели, какой должна быть качественная документация. Но как решить обозначенные проблемы? Итак, вопрос:

Как создать качественную документацию?

▫️Автоматизируйте создание задач. В таск-трекерах настраивайте автоматическое создание задач на техписов, когда менеджер продукта (продакт) ставит задачу разработчикам.
▫️Регулярно опрашивайте продакта или собирайте релизноутс (заметки о новом в версии). Общайтесь с командой или получите доступ к их планам на релиз.
▫️Посещайте созвоны, которые проводит команда продукта. Вам нужны те встречи, на которых они рассматривают или показывают доработки.
▫️Продумывайте структуру документации, уменьшайте вложенность статей.
▫️Пишите на языке вашей аудитории.
▫️Следите за гигиеной текста. Ошибки и опечатки мешают восприятию документации.
▫️Проводите тестирование документации.
▫️Улучшайте поиск. Если нет возможности улучшить движок, подстраивайте заголовки и подзаголовки под возможности поиска и поисковые запросы.
▫️Не пренебрегайте сео (seo), особенно, если у вас пользовательская документация. Люди чаще гуглят, чем читают официальную доку.

Как и обещали, делимся записью Карьерного разговора с Николаем Волынкиным.

Делимся записью карьерного разговора "Кем мы станем, когда вырастем" с Николаем Волынкиным - автором канала @docops, в прошлом техническим писателем. Сейчас Ник занимается Developer Relations в компании nil.foundation.

Ник поделился опытом смены разных профессий, мыслями об ответственности и задачах, которые та или иная роль могут решать. За час мы успели разобрать вопросы:
▪️ кто такие технические писатели и какие задачи они могут решать;
▪️ какие навыки важны для технических писателей;
▪️ что общего между системным аналитиком и техническим писателем;
▪️ когда стоит нанимать технического писателя, а когда можно закрывать потребности и другими ролями;
▪️ про метрики документации и работы технических писателей;
▪️ как можно стать техническим писателем и что для этого надо делать.

☝️Основные навыки, которые помогают быть успешным, по мнению Ника:
▪️ умение учиться;
▪️ сохранять баланс между жизнью и работой;
▪️ понимать, в чем ценность вашей работы и умение об этом рассказывать.

📚Книги, которые повлияли на Ника:
▪️ «Проект «Феникс». Роман о том, как DevOps меняет бизнес к лучшему»;
Джин Ким, Джордж Спаффорд, Кевин Бер
▪️ Серия книг Элияху Голдратт:
▪️«Цель. Процесс непрерывного совершенствования»;
▪️ «Цель-2. Дело не в везении»;
▪️ «Критическая цепь».


📝Полезные материалы:
▪️ Курс на Coursera о том, как учиться.
▪️ Лучшая документация о продукте Stripe по мнению Ника.
▪️ Любимый инструмент для документации: Sphinx.

#мемница
Когда ты джун (и не только)

#какэтоработает #писалитирекомендует
Всем привет!

По следам мема прошлой недели давайте поговорим о критике текста :)

Когда вы начинаете писать тексты, то, скорее всего, к ним первое время (да и не только первое) могут прилетать правки. Не стоит относиться к комментариям так, словно ваша карьера на этом закончилась и вас сейчас выгонят с работы. Нет! Ревьюер обычно оценивает именно текст, а не вас, если это не какой-то частный случай с вашим заклятым врагом.

Когда могут быть полезны правки?

1. Когда вы долго сидите над текстом, то глаз так или иначе “замыливается”.
Из-за этого вы можете не заметить сложных оборотов, опечаток или чего-то ещё. Поэтому если вам оставили комментарий, что “сложное предложение”, “опечатка” или “не хватает запятой”, и вы понимаете, что ревьюер прав, значит, всё в порядке. Поблагодарите коллегу и исправьте ошибку.
2. Когда вы попадаете под “проклятие знания”.
Например, если вы долго сидели над новой фичёй, то при её описании вы можете не заметить, как пропустили какой-то шаг. А всё из-за того, что в вашем восприятии он отложился как “само собой разумеющееся”.
3. Когда вы только начинаете свой писательский путь.
Это самое лучшее время для впитывания замечаний от более опытных коллег. Поэтому если пришло 20 комментариев на одну статью — это не всегда плохо :) Плохо, если они не конструктивны, а в остальных случаях — очень полезны.

Если вы понимаете, откуда растут ноги критики или ревьюер подробно объяснил свою точку зрения, правки всегда будут иметь положительный эффект. И ваша задача — провести работу над ошибками: понять, за что зацепился ревьюер, исправить это и в дальнейшей работе придерживаться новой установки. Возможно, сначала придётся себя “насильно” поправлять, но в какой-то момент вы привыкните.Так вы совершенствуетесь.

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

🎤 Аманда Палмер — спикерша TED, чьё выступление в своё время вызвало шквал положительных реакций. В своей заметке о подготовке к выступлению она выразила благодарность 105 людям, которые давали обратную связь по её речи (изначально — тексту). Потому что каждая точка зрения может привнести в речь (или в нашем случае текст) что-то, чего в ней не хватает, но что будет полезно.

📚 А если вы ну очень плохо воспринимаете критику, попробуйте прочитать книгу Джианг Джиа А я тебя “нет”. В ней он рассказывает, как плохо переносил отказы, как начал с этим бороться и какие выводы для себя сделал. А реакция на критику и отказы может быть очень похожей, ведь в обоих случаях мы боимся быть отвергнутыми, высмеянными и, возможно, униженными.

В общем, не бойтесь критики, если она конструктивная — она поможет вам стать лучше как профессионалу. И какой бы она ни была — не воспринимайте её на свой счёт.

А как вы относитесь к комментариям к вашему тексту?

#практика #пользовательскоеписалити
Всем привет! С вами Техписалити! Практика.
Спасибо всем, кто присылал домашку. Не забывайте, что у нас не диктатура кураторов, и можно возражать, если особо хочется.
Целевая группа: начинающие без опыта работы.
Уровень сложности: минимальный.

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

С чего начать? Конечно, любая дока начинается со скелета. Но как его построить?
В нашей практике встречались два разных подхода создания структуры:
- по интерфейсу,
- по процессам.

1️⃣По интерфейсу

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

2️⃣По процессам

Более сложный вариант, требует полного погружения в продукт. Структура выстраивается от начала использования, простого старта до сложных настроек. При этом описываются объекты системы, их классификация, их взаимодействие, а также пользователи, их роли и права.
Только так описываются сложные продукты и системы, примерно такого описания требует ГОСТ.
Как может выглядеть структура:
- О продукте
- Подключение
- Быстрый старт
- Панель администратора (как попасть, все объекты, права, роли, настройки, процесс)
- Пространство пользователя (как попасть, доступные настройки и работа с продуктом)
- Интеграции или API
- Решение проблем или частые вопросы.

🔆А теперь - задание

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

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

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

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

#циталити
Автор цитаты — Арина Балерина

Всем привет!
Нас зовут Лида, Маша и Катя, и мы технические писатели)

Этот пост — навигатор по каналу. Переходите по тегам и читайте то, что вам нужно.

#начало — информация о том, с чего начать.
#колонкаредактора — наши мысли о проблемах профессии. (а тут - грейды)
#выпуск — пошаговый путь в технические писатели. Мы нумеруем выпуски по порядку.
#такбывает — истории из практики.
#вопросвлоб — разбираем частые вопросы, которые звучат на собеседованиях.
#какэтоработает — рассказываем о рабочих процессах.
#практика — практические задания. Помечаем дополнительными тегами, чтобы обозначить область документации.
#пользовательскоеписалити — публикации о создании пользовательской документации.
#личныйОпыт — рассказываем, как сами преодолевали какие-то трудности.
#писалитирекомендует — лучшие практики, методологии или приёмы.
#циталити — полезные цитаты опытных техписателей.
#мемница — рубрика с мемами. Новые знания откроют для вас целый пласт профессионального юмора.
#невыдуманныеистории — интерактивная игра, как устроиться и начать работать техническим писателем.
#средаразработки — рассказываем о терминах в IT, с которыми может столкнуться технический писатель.
#предложка — отвечаем на ваши вопросы.

Впереди ещё много тем и новых рубрик. Учитесь с нами)

#вопросвлоб
Продолжаем разбирать вопросы из собеседований.
Итак, вопрос, который вам зададут с вероятностью в 99,9%:

Почему решили уйти с предыдущего места работы?

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

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

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

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

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

Готовьте свой ответ заранее. Это поможет вам быть убедительным и частично избавиться от стресса.

Всем привет! Это сообщение для опытных коллег)

Костя Медведев вчера всполошил весь телеграм - зовёт в спикеры мегакрутой конференции😉. Для тех, кто не в курсе, и для тех, кто еще не принял решение:

30 ноября и 1 декабря пройдёт конференция по управлению знаниями

🔆KnowledgeConf 2023!

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

🔸Станьте спикером конференции!

Почему мы поддерживаем Костю и KnowledgeConf 2023?

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

💚Понимать ценность своей работы и уметь о ней рассказывать.

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

подавайте доклад здесь: 👉 https://cfp.knowledgeconf.ru/
Там же можно прочитать про сроки, этапы, подробности, условия и всякие плюшки спикерам.

Если есть вопросы или нужна дополнительная информация, смело пишите руководителю Программного комитета Косте Медведеву: @medvedevkonstanteen.

Вперед!❤️