#какэтоработает
Всем привет! А вы замечали, что прежде чем читать, мы сканируем текст? Заголовки, врезки, схемы, картинки, иконки - всё это точки внимания, которые проводят нас по статье.
Задача технического писателя - создать статью, которая приносила бы пользу даже при сканировании, а не только при чтении.

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

1️⃣ Подзаголовки должны отвечать на условный вопрос заголовка. Например:

Как настроить схему работы (заголовок)
- Создайте статусы (подзаголовок)
- Создайте переходы (подзаголовок)
- Настройте правила переходов (подзаголовок).

Можно использовать с отглагольными: Настройка, Создание.
В этом случае человек пробегается по точкам внимания и уже знает, что ему делать.

2️⃣ Выделить много - не выделить ничего. Хрестоматийное правило требует аккуратно выбирать визуальные якори. Если выделить мало не получается, например, в тексте часто упоминаются элементы интерфейса, используйте списки или схемы.

3️⃣ Каждому элементу - свой стиль. Если вы используете полужирное начертание, делайте это осознанно. Например, выделяйте только элементы интерфейса. Если вы хотите выделить какую-то мысль, используйте режим примечания. Не забывайте, что слишком выделенный элемент мозг отсекает, как назойливый рекламный макет. Не старайтесь выделить все, помните о правиле №2.

Тестируйте статьи на себе и коллегах при ревью.

#какэтоработает
Всем привет! Вы написали документацию и проверили её с точки зрения языка и стиля. Что происходит дальше?

Тестирование документации

Любую документацию нужно проверить: не вводит ли она пользователей в заблуждение?

🔸Как в идеальном мире

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

🔸Как чаще всего

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

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

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

Помните: если у пользователя будет шанс ошибиться, он ошибётся. Не жалейте своих формулировок, исправляйте, если сомневаетесь в них.

Вычитайте текст снова, избавьтесь от возможных опечаток и ошибок.

Когда документация проверена, публикуйте её. Заканчивается ли на этом её тестирование? Конечно, нет. Встречали в мемах формулировку тестирование на пользователях? Так вот, это не совсем мем.

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

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

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

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

#мемница
С днём знаний! 🎓

#вакансии
Всем привет!
Воскресный пост с интересной вакансией для уверенных джунов.

Наша коллега Ольга из Айрим (Сколково) сейчас в поисках напарника - технического писателя, который влюблен в возможности ИИ и медицину, не боится ГОСТ и владеет начальным английским. Удаленно можно. Тонкостям из предметной области обучат за счёт компании.

Продукты Айрим помогают врачам анализировать результаты томографии, маммографии, рентгенографии, УЗИ и других важных исследований.

Подробнее о вакансии читайте в Олином посте в большом чате техписов, спрашивайте в комментариях или личных сообщениях.

#какэтоработает #пользовательскоеписалити
Всем привет!
Сегодня холиварная тема, а именно:

Пользователь должен или может?

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

1️⃣ Долженствование
Первое, что мы запоминаем: пользователь никому ничего не должен. Поэтому модальные с этим оттенком смысла употреблять не рекомендуется. Замените должен или обязан глаголом повелительного наклонения или изъявительного в форме 3 лица (по вашей редполитике):
Пользователь должен нажать Сохранить.
Пользователь нажимает Сохранить.
Нажмите Сохранить.

2️⃣ Запрет
Так же как и обязанности, мы не можем вменить пользователю и запрет на действия.
Редактировать карточку запрещено.
Не редактируйте карточку, это приведет к ошибкам (таким-то).
Если пользователь отредактирует карточку, система выдаст ошибку.

3️⃣ Невозможность
Мы не можем определять, что пользователь в состоянии выполнить, а что нет. Но мы можем обозначить, что чего-то не делает наш продукт.
Редактировать карточку нельзя.
Редактировать карточку могут только пользователи с правами администратора. Или Редактирование карточки не предусмотрено.

4️⃣ Желание
Говорить о желаниях пользователя - тоже не задача документации. Неважно, что хочет пользователь, важно, что может продукт.
Если хотите создать заявку...
Чтобы создать заявку...

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

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

#выпуск 6
Всем привет! Как и обещали, возвращаемся с рассказом о вакансии.
Но сначала - результаты опроса. Спасибо всем, кто участвовал!

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

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

❗️Человек, который поставил "30 000", напишите мне в личку @litulyagan, побеседуем о вашей карьере. Это бесплатно.

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

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

И к вакансии. Техписателя ищет команда WB Cloud. Это в одной компании со мной (Лида). Задача - поднять документацию с нуля и настроить процессы документирования. Самый огонь для смелых и плюс в резюме.
Подробно вакансия описана на hh. Пусть вас не пугает обозначенный опыт, смотрят всех. Вопросы и резюме можно отправлять Насте.

#анонс
Всем привет!

Уже в этот четверг, 28 сентября, в 19:00 по московскому времени пройдёт митап для технических писателей, организованный коллегами из Ozon Tech и X5 Tech.

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

► Арина Кузнецова из Ozon расскажет об атрибуциях документации: какие документы помогают облегчить работу с текстами и сделать их понятнее.
► Владимир Гусаров из X5 Tech расскажет, зачем нужны стайлгайды и какие проблемы они решают.
► Круглый стол «Роль технического писателя в продуктовой команде»

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

Всем привет!

Организаторы конференции технических писателей TechWriter Days #1 сообщают, что открыли регистрацию и прием докладов.

Конференция пройдет 5-6 апреля 2024 г. в Москве в гостинице "Holiday Inn Сокольники".
Формат конференции: офлайн + онлайн.

До 31.10.2023 действует super early bird период оплаты.

Сайт мероприятия: https://techwriterdays.ru/
Телеграмм: @twdays

🔆А теперь информация для слушателей:

Как сходить на конференцию и получить максимум пользы

Пост Екатерины Ушаковой из Ozon Tech про то, как посещать конференции с пользой

#выпуск 7
Всем привет!
Сегодня у нас важная тема, которая волнует всех новичков:

Как получить опыт, когда всем нужны готовые специалисты?

1️⃣Учитесь и делайте учебные проекты

Кто-то скажет: это всё ерунда. Но на самом деле сидишь на собесе, и такой хороший по софт скиллам соискатель попался, и команде понравился, но технически не подкован. И ты думаешь: "Ну скажи, скажи, что ты хотя бы учился, хотя бы читал!" - и нет(
Учебные проекты - это как раз для таких случаев.

2️⃣Ищите "простые" работы и внедряйте технологии там

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

3️⃣Ищите стажировку

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


4️⃣Ищите "продвинутую" работу и не теряйте надежду на везение

Можно попасть в команду, которая готова подтянуть в вас технические знания или знания инструментов, если вы хорошо пишете и любите тексты. Это, например, такие случаи, о которых рассказывал Семен Факторович.
Взамен вы можете помочь команде с другими задачами, например, вести блог или канал с обновлениями.

И помните о самом главном: огонь в глазах может компенсировать отсутствие знаний.

#анонс
Всем привет!

Уже в эту пятницу, 20 октября, в 18:00 по московскому времени пройдёт митап для технических писателей «TeamSnack TechWriters», организованный коллегами из Cloud.ru.

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

► Юрий Никулин из Cloud.ru расскажет о документации как о рок-н-ролле, части продукта и части продуктового процесса.
► Анна Атаманова и Алексей Миронов из SberWorks поразмышляют о противостоянии когнитивного стресса и знаний и о том, как выжить в мире перегрузки мыслей
► Екатерина Ушакова из Ozon поделится мастерством в технической документации: структурой, качеством и метриками.
► Сергей Кулаков из Cloud.ru расскажет о CopycatCatcher — бесплатном умном инструменте для авторов и менеджеров баз знаний.

Митап можно посмотреть онлайн или приехать в московский офис Cloud.ru. Регистрируйтесь на митап в любом формате по ссылке.

#какэтоработает

Всем привет!
Давайте поговорим о довольно важном документе — Release Note.

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

🫅🏼 Пользовательские релиз ноты — это заметки к релизным версиям продукта.
Когда обновляете приложение на телефоне, то на странице в магазине вы наверняка видели блок «Что изменилось?» или «Что нового?» и небольшой список изменений. Это и есть «пользовательские релиз ноты».

Сюда обычно пишут изменения, которые коснулись пользователей напрямую: например, появился новый функционал, изменился дизайн, усилена безопасность. Язык таких релиз нотов должен быть простым и понятным любому человеку. Здесь не должно быть сложных технических терминов.
Но не забывайте про ЦА! Если ваш продукт рассчитан, например, на системных администраторов, будет странно, если в нотах все термины будут разжёваны так, словно читатель — первоклассник.

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

🧑🏼‍💻 Технические релиз ноты обычно нужны разработчикам внутри компании и в целом их можно назвать внутренними.

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

Кроме самих разработчиков, к релиз нотам часто имеют отношение технические писатели. Они могут:
1. Настроить процесс релиз нотов. Иногда случается, что в компании вообще релиз ноты не пишут, хотя стоило бы.
2. Следить, чтобы у новых версий продукта всегда был релиз нот.
3. Собирать технические релиз ноты и делать из них новости продукта для пользователей.
4. «Переводить» технические релиз ноты на «человеческий» язык, чтобы любой человек из компании понял, что изменилось.

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