#колонкаредактора #грейды
Грейдер технических писателей по версии школы Техписалити!

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

Грейды технических писателей

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

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

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

Можно ли быть синьором, не зная XML? Да, например, если вы работаете с ГОСТ.
Можно ли, умея писать скрипты на Python, не быть синьором? Да, если вы не способны построить структуру документации.

Мы собрали свой опыт, опыт друзей-техписателей, информацию из других грейдеров и грейдеров смежных областей и подготовили свой упрощенный и унифицированный список грейдов школы Техписалити!

Но это еще не всё)

Мы приглашаем каждого из вас к разработке общего грейдера. Переходите по ссылке и оставляйте комментарии под постом или в этом документе.

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

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

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 про то, как посещать конференции с пользой