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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Замечали, что некоторые тексты читаются легко и быстро, а некоторые написаны так сухо, что пробираешься сквозь знакомые слова, словно идёшь через болото? Такое происходит из-за ряда причин, и о некоторых из них мы сегодня поговорим.

Что же мешает тексту быть простым и динамичным?

📌 Длинные предложения
Предложения, которые занимают две-три строчки текста, очень нагромождают текст. Более того, без условных пауз читатель может уже забыть о том, что было в начале. Начнёт перечитывать, подумает о своём и опять ничего не поймёт. По заветам Ильяхова: сокращайте! Дробите сложные предложения. Дробите абзацы. Чем проще синтаксические конструкции в предложениях, тем проще читать и понимать тексты. В конце концов, мы с вами не Львы Толстые.

📌 Отглагольные существительные
Текст читается легче, если он динамичный. Динамичным текст делают глаголы. Старайтесь не использовать отглагольные существительные — они «замедляют» текст и делают его сложнее для восприятия. Если есть отглагольное существительное, то, скорее всего, его можно превратить в обычный глагол. Сравните:
► «Для открытия формы записи нажмите кнопку “Анкета”».
► «Чтобы открыть форму записи, нажмите кнопку “Анкета”».
А если ещё добавить первый пункт:
► «Чтобы записаться, нажмите кнопку “Анкета”».

📌 Много существительных подряд
Пункт пересекается с предыдущим, но иногда бывает так, что в тексте долгое время не встречаются даже отглагольные существительные. Наверняка вы встречали предложения, в которых несколько существительных идут подряд. Такие тексты выглядят сухо и плохо читаемы. Сравните:
► «Для поддержания здорового внешнего вида хранение фруктов и овощей допустимо в специально отведенных местах».
► «Храните овощи и фрукты в специально отведённых местах, чтобы они дольше оставались свежими».
Текст сразу становится более динамичным и дружелюбным.

📌 Модальные глаголы
Вы решили разбавить текст глаголами, но разбавили модальными. Это тоже не очень хорошая практика. Это не относится к динамичности, но, скорее всего, ваш текст не пострадает, если глаголы вроде «может», «должен», «нужно» и прочее удалить. Да, это разбавляет текст, но не делает его динамичным. Скорее делает его неуверенным. Сравните:
► «Чтобы вызвать лифт, нужно нажать кнопку вызова»
► «Чтобы вызвать лифт, нажмите кнопку вызова»
Иначе можно задаться вопросом: кому нужно? Мне, лифтёру или консьержке?
Повелительные формы глаголов — ваш друг, они сделают текст более уверенным. Если, конечно, в вашей редполитике не написано иначе.

Расскажите, какими ещё внутренними установками или правилами вы пользуетесь, чтобы сделать текст более динамичным?

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

Всем привет!
Делимся информацией о бесплатном митапе для техписателей и их тимлидов.

6 марта Лаборатория Касперского (оттуда родом наша Катя😊) проведет Kaspersky Tech Fest.

Какие темы раскроют:

1️⃣ Поиск техписателей.
2️⃣ Онбординг и адаптация.
3️⃣ Развитие и карьерный трек.

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

Кому интересно — в Лабораторию Касперского часто берут стажёров. Страница с вакансиями легко гуглится по запросу "стажировка касперский".

Кстати, и про стажёров тоже расскажут. И на вопросы обещают ответить.

Регистрироваться вот здесь. Мы уже)

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

Всем привет! Сегодня поговорим об одном из самых популярных терминов в речи техписателей – docs-as-code.

Что такое docs-as-code?

🔆 Это подход к созданию документации, когда техписатели используют инструменты и практики разработки. По мнению documentat.io, docs-as-code подразумевает, что технические писатели выполняют хотя бы часть из указанных процессов:
– Пишут документацию в редакторах кода вроде VS Code и подобных.
– Используют языки разметки, например, Markdown или reStructureText.
– Хранят исходники в гите и используют его для совместной работы с файлами.
– Используют программные решения для “компиляции” документации – преобразования исходников в html-страницы. Такие инструменты называются SSG (Static Site Generator), чаще используется термин “генератор” или “сборщик”.
– Разворачивают документацию как приложения – с помощью так называемой технологии непрерывной интеграции и развёртывания (CI/CD).

Почему команды выбирают такое решение?

Аргументов “за” docs-as-code много. Рассмотрим три основных.

1️⃣ Первый, но не самый очевидный, – единый мир с продуктовой командой. Технические писатели, которые обычно отвечают за буквы и считаются гуманитариями, в этой парадигме полностью интегрируются в команду. Они неизбежно начинают разбираться в процессах разработки, лучше понимают разработчиков, а разработчики лучше понимают их.

2️⃣ Второй аргумент, самый веский – подход docs-as-code помогает создавать актуальную и полную документации за счёт самого процесса. Документация развивается и обновляется одновременно с продуктами.


3️⃣ Третий аргумент – гибкость решений и разгрузка команды, если используются генераторы. SSG, как правило, — это опенсорсные продукты с хорошей документацией и обширным сообществом. Благодаря этому технические писатели могут освоить инструмент самостоятельно и наладить сборку документации.

Если с инструментами разработки всё понятно, то что же значит “использовать практики разработки”? Об этом мы поговорим в следующем посте.

А пока давайте вспомним, какие же ещё плюсы у docs-as-code и какие недостатки?