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

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

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

Всё, что мы сделали - добавили описание и решение ошибок, которые возникают, если вагончики этого "поезда" всё-таки перепутали.

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

Итог: средствами документации можно решить многое, но далеко не все. И если что-то идёт с трудом, эффективнее улучшить сам продукт. Так бывает.

#выпуск 4

Всем привет! Поговорим о том, что скрыто в вакансиях?

После того, как вы определились, какую документацию вы хотите писать, можно начать искать вакансии. Да-да, сначала вы можете поискать вакансии, а уже после этого составлять резюме. Зачем это делать? Есть несколько причин.

► Поймёте, нужно ли вам оно. Может, вам это тех.писательсво вовсе не подходит, и вы хотите писать сценарии для обучающих роликов (что, кстати, тоже может быть документацией, но об этом мы поговорим позже).
► Узнаете, какие критерии компании ищут в соискателях. Это поможет вытащить ваши навыки и опыт выше.
► Выясните, какие технологии используют, что вы можете подучить без обязательного опыта. Например, многие технические писатели пишут на языке разметки Markdown. Пока вы ищете работу, вы можете почитать об этом языке и попробовать писать на нём. Кроме того, тестовые задания, выполненные в этом языке разметки дадут вам дополнительные бонусы.
► Изучите, что предлагают работодатели. Нередко бывают случаи, когда компании хотят сэкономить и пытаются одной вакансией закрыть две, а то и три ставки. Например, совмещают технического писателя и аналитика. Или копирайтера, подавая это тем, что “ну ты же всё равно работаешь с текстами”. Подумайте, насколько это вам интересно и нужно.

Давайте остановимся на последнем.

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

Часто можно встретить формулировки, что будет входить в вашу обязанности, типа «Составлять технические задания», «Общаться с заказчиками», «Писать тексты для соц.сетей», «писать UX-тексты», «Тестировать продукты». Может показаться, что это действительно работа для технического писателя, однако это не так. Первые два — работа аналитика. За этим может скрываться, что аналитика в компании нет, так что вам придется взять на себя эту ношу. Третий и четвертый тип — это больше к маркетингу и копирайтерам. А последний вообще к тестировщикам.

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

Расскажите, что вас привлекает в техническом писательстве?

#вопросвлоб
Вопрос из прошлого поста
мы задали неспроста, извините за рифму.
Это то, что у вас спросят на собеседовании. По крайней мере у нас его задавали в 100% случаях. Подготовьтесь заранее.

Почему вы решили стать техническим писателем?

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

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

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

Сформулируйте свой ответ, напишите его, прочитайте. Этот ответ должен убеждать в первую очередь вас. И если вы почувствовали, что да, вы действительно хотите стать техническим писателем, вы готовы)

Всем привет!

У нас появилось много новеньких, поэтому давайте знакомиться!

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

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

Мы создали этот канал, чтобы помочь тем, кто хочет стать техническим писателем, и тем, кто совсем недавно на этом поприще. И очень хотим, чтобы посты были интересны и полезны для вас. Поэтому если есть какие-то вопросы о техписательстве — пишите, будем передавать опыт или разбираться вместе :)

Напишите в комментариях, в какой сфере вы работаете сейчас? Или из какой пришли в техписательство?

#какэтоработает
Подходы к созданию документации: интерфейсный и сценарный

Три автора этого канала родом из одной компании, и в ней мы практиковали два подхода:
1. Интерфейсный
2. Сценарный (кейсовый).

Всё довольно просто.

► Интерфейсный подход

Bы отвечаете на вопрос: Что может продукт?
Описываете возможности — все, что можно выполнить. Как выглядит интерфейс, какие есть поля, какие кнопки, какие процессы они запускают.
Для этого достаточно зайти в продукт и покликать по всем кнопкам.
Таким же образом и создается, например, справочник API (программного интерфейса). Вы просто перечисляете все методы и описываете, как они работают и что возвращают в ответ за запросы.

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

► Сценарный подход

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

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

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

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

Как правило, документация сочетает эти два подхода и содержит и те, и другие статьи.
Оставляйте свои вопросы в комментариях.

В следующем посте ждите практическое задание. Начнём составлять ваше портфолио)

#практика #пользовательскоеписалити
Всем привет!

Для тех, кто только приходит в профессию, мы подготовили практический курс Техписалити! Практика.

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

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

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

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

Вы можете запросить кросс-ревью и показать текст такому же ученику Техписалити! Практики.

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

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

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

#практика #пользовательскоеписалити
Вот и первая практика. Готовы?)
Целевая группа: начинающие без опыта работы.
Уровень сложности: минимальный.

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

Задание 1

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

Задание 2

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

Общие требования:
1. В статье должен быть заголовок.
2. При необходимости разделяйте текст на части по смыслу, используя подзаголовки.
3. Если считаете нужным, добавьте картинки (скриншоты).

Пишите так, как получается. Пусть это будут черновики, на которых мы будем модулировать настоящую работу техписов, проводить ревью и вносить правки)
С каждым новым уроком вы будете совершенствовать свои тексты и позже на них же отрабатывать более сложные инструменты.

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

Встретимся через неделю на новом занятии Техписалити! Практики.

#личныйОпыт

Пока те из вас, кто решился, жарят шашлыки делают практическое задание, мы решили, что пора познакомиться поближе и начать делиться личными историями.

Глава I: Из грязи в князи декрета в IT.

Всем привет! Меня зовут Катя, по образованию я переводчик-лингвист, в душе поэт-песенник а на деле технический писатель. Сейчас работаю в Лаборатории Касперского над одним из b2b продуктов. Обожаю английский язык, люблю тексты и выяснила, что "гуманитарий" - это не приговор.

До того, как прийти в техписательство, я довольно продолжительное время трудилась переводчиком в нефтегазовой отрасли. Однако после выхода в декрет и переезда в другой город передо мной встал вопрос: "Кем же стать, когда вырасту?" Пойти по пути наименьшего сопротивления не удалось, т.к. сходив на пару собеседований и словив вьетнамские флешбэки, я осознала, что в нефтянку больше не хочу. Тогда-то муж и посоветовал мне попробовать себя в качестве технического писателя. К сожалению, анализ имеющихся вакансий принёс не слишком утешительные результаты. "Войти в айти" на тот момент для меня казалось чем-то тяжело воплотимым: даже джунские вакансии подразумевали наличие хоть какого-то технического бэкграунда. Тем не менее, сдаваться я не собиралась - написала отдельное резюме для отклика на техписательские вакансии, сделав акцент на опыте работы с техническими текстами и высоком уровне грамотности, прошла курс по локализации от Google и начала смотреть в сторону курсов по техписательству. Но помогло мне в итоге... банальное везение. Откликнувшись однажды на вакансию IT-переводчика, я услышала в трубке слова от рекрутера: "На самом деле эта должность скорее ближе к должности технического писателя... Вы не против?" В голове моей тем временем крутилось: "Shut up and take my application!"

И вот, почти 2 года спустя, я вновь окунулась в процесс поиска работы. Каково было мое удивление, когда выяснилось, что интересных вакансий для технических писателей существенно больше, чем для переводчиков, и уже намного чаще эйчары первые находят меня и зазывают к себе в компанию. Тем не менее, переводческого опыта у меня по-прежнему было гораздо больше, чем техписательского. Поэтому на собеседованиях неизбежно звучал вопрос: "Почему вы хотите работать техническим писателем, а не переводчиком?"

Что я делала в таких ситуациях:

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

И, судя по всему, эти ответы были более чем удовлетворительными)

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

Всем привет!

Сегодня вечером в 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.