Привет!
Я Лида, технический писатель. В этом канале я буду делиться полезной на мой взгляд информацией для начинающих русскоязычных технических писателей и других специалистов, которые управляют знаниями.
О себе:

Бэкграунд:
Журналистика - 9 лет
Госслужба и администрирование проектов - 2,5 года
Копирайтерство и редактура - с 2004 года.
В технической документации - с 2021 года.

Обучение:
Журфак БелГУ
Программирование в Бауманке
Intel Technical Writing School
Xsolla Docs School
Гипербатон в Яндексе.

Работа:
Яндекс
VK
r_keeper
ВБ Тех

#начало
Если вы решили уйти в техписатели, главное, что вам нужно - хороший русский: грамотность и инфостиль.

Корректоров в технической документации нет. Да и редакторы - редкость.

Итого:
Нора Галь, Чуковский, Ильяхов.

Берите любые школы, какие только можно. Кроме курсов техписателей в "Специалисте" при Бауманке. Вам туда, если вы хотите описывать научные исследования.

Еще вам нужен Семен Факторович. Это как Ильяхов, только в технической документации. И так же, как с Ильяховым, со временем наступит момент, когда вы перерастете потребность в нём)

Но начать с Факторовича стОит.

Идеально, если у вас будет ментор - человек в практике, который будет вашим наставником.

Хорошая новость! Авторов в этом канале будет два) Второй автор - моя коллега, мастер маркетинговых коммуникаций, технический гуру в Ozon и гроза всех багов - Мария Щеблякова.❤️

Еще хорошая новость!😂 третий автор в канале - англоязычный технический писатель в Лаборатории Касперского - Екатерина Марченко.❤️

И прежде чем мы начнём делиться знаниями, поприветствуем в подписчиках этого маленького канала очень большого человека в технической документации, проповедника подхода Docs-as-code (документация-как-код) - Ника Волынкина.

Ник, спасибо, что ты с нами❤️.

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

Помчали)

Скажу вероломную вещь, но мне кажется, что технический писатель — наиболее христианская из всех профессий в IT. Никакая деятельность не завязана так на любви к ближнему, как эта. Разработчик напишет фичу просто по ТЗ, продакт проконтролирует выполнение целевых показателей, KPI, — всё, они отработали. И только техписатель не работал или работал зря, если не помог пользователю.

Свежий кейс: 16,1% желающих купить один из наших продуктов в итоге отказываются от покупки. Почему? Система у них "не взлетает" уже на этапе авторизации (там авторизация с интеграцией, дело непростое). Плохой продукт? Наша техподдержка выяснила, что причина в другом: все эти люди либо не читали документацию, либо не поняли её.

Я помню эту инструкцию. Полгода назад мы работали над ней все вместе: технические писатели, продакт, тестировщик и поддержка. Мы проверили все вдоль и поперек, пропустили через несколько этапов ревью, модерации. Статья казалась нам идеальной и исчерпывающей. И вот выходит, что ее никто не читает.

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

Почему же ее не читают?

1. Ее трудно найти. Этот вариант отметается: ссылка на статью (большими буквами) есть на экране авторизации.
2. Ее находят не вовремя. Будем честны, ссылки на экране авторизации уже никто не кликает, там уже авторизовываются. Значит, ссылка на статью появляется поздно. Рассказать о способе авторизации нужно заранее. Там, где человек только знакомится с продуктом — на продуктовом сайте, на лендинге. Конечно, на продуктовом сайте никто не будет читать инструкции. Но здесь вполне подойдет схема, визуализация процесса.
3. Она написана неудачно. В этом наша главная ошибка, вероятно, — мы накатали идеальную пошаговую простыню со скринами совершенно без схем. Подробно, правильно, но непонятно.

Мы еще проведем опрос, но результат почти очевиден. Инструкция незаботлива, она размещена и написана без любви, без эмпатии. Это и предстоит исправить. Будем держать в курсе.
P.S. Постаралась прикрутить комменты, ждем вопросов и отзывов.

Опрос из чата технических писателей https://news.1rj.ru/str/technicalwriters.

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

#выпуск 1
Итак, вы решились сменить профессию и стать техническим писателем. С чего начать?

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

Анализируем опыт. И сразу занимаемся резюме, готовьте черновик, потом доработаете.
Что релевантно:
1. Вы создавали и редактировали тексты, желательно околоайтишной тематики.
2. Вы описывали какую-то последовательность действий, инструкцию. Например, описывали для читателей, как купить билет на сайте.
3. Вы писали техническое задание, описывали какие-то требования, например, для госзакупок или подобное.
4. Вы проводили интервью, опрашивали кого-то.
5. Вы создавали регламенты или проекты нормативно-правовых актов.
6. Вы имели дело с медиа, снимали скринкасты, проводили презентации.
Если хоть на что-то ответили "да", идем дальше.

Вот тут пришла мысль, что надо отдельный пост писать про резюме - как его готовить тем, кто переходит из не IT. Чуть позже.

Если у вас нет опыта техписательства:
1. Нужно подготовить что-то вроде портфолио.
2. Будете соглашаться выполнять тестовые.

Создавать статьи для портфолио будем прямо здесь)

А, и да, самое главное - не забывайте учиться) Все уже посмотрели лекции Факторовича?)

#выпуск 2
Всем привет!
В прошлом посте мы проанализировали свой опыт и навыки.
В этом — попытаемся найти своё место в огромном мире технической документации. И от нашего выбора будет зависеть, что именно мы будем изучать.

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

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

Для такого рода документации важно писать в инфостиле - кратко и понятно.

2. Документация для разработчиков.
Это инструкции для тех, кто создает продукт и интегрирует его с другими, а также для сторонних разработчиков. Сюда можно отнести внутреннюю документацию, которая касается кода.

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

3. Документация по ГОСТ. Документация для госзаказчика, для патентования и прочее. Документация включает и руководство пользователей, и руководство администратора, и описания кода. Только в отличие от предыдущих направлений здесь важно не только содержание, но и форма, строго закрепленная в ГОСТах.

Здесь важно ориентироваться в ГОСТах 19 и 34 и любить довольно сложный и сухой стиль изложения.

В пределах одной компании может встречаться как одно из этих направлений, так и два, а то и все три.
Напишите в комментариях, какое из направлений вам ближе?

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

#выпуск 3
Всем привет!

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

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

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

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

Подумайте, чем вы сейчас занимаетесь. Возможно, вы…

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

Всё это — опыт, который может сыграть на руку. Акцентируйте на нём внимание, подвиньте выше в ваших "обязанностях". Кроме этого, добавьте:

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

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

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

P.S.: не забывайте про знание английского языка. Иногда в IT компании требуются люди для перевода документации. И это тоже может быть отличным способом войти в профессию.

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

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

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

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

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

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

#выпуск 4

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Всем привет!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Задание 1

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

Задание 2

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

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

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

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

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