Меня зовут Ирина Исай, я техрайтерка киберспортивного медиахолдинга WePlay Esports, части холдинга TECHIIA. В предыдущей статье я рассказывала об , подходах и лучших практиках. После материала я получила много вопросов от коллег по цеху и тех, кто думает перейти в техрайтинг, как писать и структурировать документацию.
Поэтому в этой статье поделюсь своим опытом. Он может быть полезным и для продуктовых команд, и для техрайтеров. Не воспринимайте советы как правила: это мои собственные наработки и лайфхаки, которые я подглядывала у коллег.
Эта статья пригодится как начинающим — людям, которые только пришли в профессию и хотят разобраться, с чего начать и каких ошибок избежать, — так и техрайтерам, которые уже успели поработать и набить шишек, которых мой опыт может вдохновить на поиск новых решений при создании документации. По крайней мере я всегда интересуюсь, как пишут коллеги.
Ниже — о таком:
- с чего начинать, когда получили новый продукт для описания;
- чего точно не стоит делать при подготовке документации;
- что делать с документацией, которую писали не вы, но вам режет глаза качество, и стоит ли за нее браться;
- немного о том, какими инструментами пользуется техрайтер.
«Да что там — просто сесть и написать»
Я обожаю описывать продукты, которые еще не описывали до меня. В этом есть свои преимущества: я сама могу создать структуру документации, составить правила ее форматирования и подходы к стилю. Но это не значит, что можно просто сесть перед окном, которое выходит на океан, и, вдохновляясь вечерним бризом, написать роман!
Сначала рекомендую познакомиться со всеми, кто приобщен к созданию и поддержке продукта: пообщайтесь, соберите информацию, получите доступы к продукту, который необходимо описать.
Совет. Иногда продуктовая команда опасается давать доступ к самому продукту. Говорят, что достаточно и тестового образца. Никогда на это не соглашайтесь. Уже не раз мне приходилось переписывать свою работу, потому что, как оказывалось, то, «на чем тестируют», и то, что ушло в мир как продукт, — разные вещи. Даже интерфейс может заметно отличаться!
А еще продуктовые команды часто «экспериментируют» с наименованием полей и различных кнопок. Иногда бывают «веселые» названия на грани цензуры — ни в коем случае они не должны попасть в приличный мануал продукта! Все скриншоты делайте только с хорошенько прописанного UI реального продукта, чтобы их было не стыдно показать.
Далее посмотрите имеющуюся техническую документацию: юзер-кейсы, технические требования и тому подобное. Мне нравится ходить по доскам Jira продуктовых команд и там собирать информацию. Все собираем, структурируем (можно даже в табличку для удобства). Но даже на этом этапе, когда кажется, что появилось какое-то понимание продукта, писать мануал рано.
Когда вы получили доступы и разобрались с имеющейся информацией (или все еще собираете, ведь начали видеть какую-то логику в полученной информации), время тестировать продукт.
Например, ISO рекомендует создать профили своих читателей:
- Кто пользователи продукта, который вы собираетесь описать?
- Какие задачи они стремятся решить с помощью продукта?
- Какие уровни пользователей и как отличается доступный для них функционал?
Техрайтеру нужно перевоплотиться в каждого такого пользователя, пройти его пользовательский путь и фактически решить те задачи, которые перед ним стоят. Иногда это скучно. Иногда приходится еще раз выполнить работу тестировщика, возможно, даже более придирчиво. Но результат того стоит — ваш мануал будет целостным, словно настоящее художественное произведение: в нем будет вступительная часть, основная и концовка.
Вступительная часть — это отдельное решение. Возможно, нужно описать сначала «домашнюю» страницу продукта. Иногда логичнее начать с описания кабинета пользователя. Не волнуйтесь, вы поймете это где-то на этапе «тестирования» продукта. А иногда вам просто скажут, что сейчас нужно описать вот этот функционал, а остальные потом.
Чего я не делаю: уровни, правила, обещания
Не делаю документацию слишком глубокой по уровням. Из своего опыта и по советам коллег знаю, что если вы не Boeing, где каждая статья может иметь подстатьи, вспомогательные или смежные статьи, то ваш максимум — 3-4 уровня документации. Если больше — мануал-гайды-статьи-подстатьи — никто так глубоко не будет читать, потому что будет сложно найти нужную информацию.
Видела примеры, когда для каждой новой фичи продукта техрайтеры делали отдельную статью. Не скажу, что это плохо, но это скользкая дорога. Например, ваш продукт — слишком комплексный аналитический инструмент, который может обрастать дополнительным функционалом. Или этот функционал легко отмирает и заменяется новым. В результате статей становится так много, что их трудно найти в документации. Более того — становится трудно увидеть общую картину продукта.
Совет. Начинайте со статей высшего уровня — описательных, которые будут вступлением к мануалу о продукте или к гайду об отдельном функционале: вот продукт (функционал), он такой, делает вот это, полезен тем-то, а пользователи вот такие.
Когда есть общее описание, можно спускаться на более низкие уровни — к конкретному функционалу (или его элементам). Здесь тоже для каждого гайда или уже отдельных статей должно быть небольшое вступление, разъясняющее, о чем пользователь прочитает дальше.
По возможности я к каждой статье добавляю содержание (это можно делать, например, с Confluence) или пользуюсь различными уровнями заголовков (например, для PDF). Помните: никто не будет читать весь мануал и каждую его статью. Пользователь пробежится по содержанию, затем по заголовкам, возможно, обратит внимание на цветные блоки с подсказками и скриншоты. Но остановится только на том, в чем нужно разобраться.
В конце каждой статьи я еще даю ссылки на смежные материалы — дополнительный или смежный функционал. Никогда не делаю ссылок в середине текста: в PDF не всё кликается, в Confluence ссылки могут ломаться, когда нужно мигрировать на другой райтерский инструмент. Как правило, создаю раздел Read more в конце гайда и добавляю списком несколько ссылок.
Когда уже есть скелет — верхний уровень документации — и немного нарощенного мяса на нижних уровнях, становится понятнее, где и какой функционал должен располагаться в документации.
Для работы с документацией часто использую Confluence. Здесь веду глоссарий, таблицу версионности. Для документации хорошо иметь и статью (отдельный документ) о пользовательских и системных ролях — доступы и разрешения в продукте, который вы описываете
Уже на этом этапе создания документации начинаем понимать, как лучше называть гайды и статьи, даже заголовки разделов. Главное в названиях — чтобы читатель интуитивно понимал и находил нужную ему информацию.
Не начинаю работу над документацией без понимания своего собственного стандарта написания. Например, заголовки. Надо решить, как вы их пишете: как предложения (первая буква большая, другие маленькие) каждая буква большая; используете артикли или нет...
Совет. Заголовки — мое любимое. Иногда наталкиваюсь на такой заголовок-аббревиатуру, что и не догадаешься, о чем речь. Иногда наоборот — две-три строки текста в заголовке — пока дочитал, забыл, зачем зашел.
У меня есть правило, что заголовок должен поместиться в одну строку, а еще лучше — в половину строки. Всегда нужно помнить, что ваш читатель может пользоваться устройствами с различным размером экрана, а текст может иметь различные форматы: PDF, HTML и тому подобное. Отсюда проблема с длиной строки и возможностью его дочитать. Его может «съесть» поле экрана, а вам нужно не раздражать читателя, а дать ему возможность увидеть весь текст сразу.
Я больше пишу на английском языке, поэтому стараюсь делать заголовки с активными глаголами: «удалить__», «создать__». Когда человек ищет ответ на свой вопрос, он должен увидеть в мануале конкретное действие, которое нужно выполнить.
Но не всегда можно поставить активный глагол. Тогда приходится делать заголовок более описательным. Это тоже полезно: читатель увидит описание, и это поможет найти решение проблемы.
Форматирование заголовков и шрифтов лучше выполнять уже после написания основного материала. Для этого прекрасно иметь инструмент для написания текстов, который позволяет накладывать стиль на все тексты и корректировать их централизованно. Советы по его выбору напишу ниже в соответствующем разделе.
Не описываю то, чего не существует. Иногда продуктовые команды обещают, что вот скоро будет какой-то функционал, даже показывают его тестовый образец. А еще могут пообещать исправить, доработать уже завтра, через неделю, в течение месяца, что существенно изменит внешний вид продукта и его функционал. То есть намекают, что это можно уже описать, чтобы потом не переписывать. Ни в коем случае не поддавайтесь! Нельзя описывать ожидаемое. Что на экране — то в документации.
Рабочие моменты
Расскажу о некоторых сложностях, с которыми точно сталкивается каждый техрайтер.
Кнопка есть — функции нет. Это распространенная история. Продуктовые команды не всегда хотят вести свою техническую документацию, поэтому часто помнят только самое свежее о своем продукте. О новой кнопке расскажут все, о соседней, немного более давней, придется искать информацию в других местах. Хорошо, если человек, который ее создавал, еще работает в компании, потому что бывает иначе.
Еще веселее, когда такая кнопка или любой другой элемент просто есть, но не работает. Можно обратиться к команде, чтобы как-то их скрыть, выпилить, но это не всегда возможно, не всегда есть ресурс. В таком случае я игнорирую элемент, не описываю. Хотя остается риск, что пользователь найдет этот нюанс и начнет расспрашивать — тогда будет немного неловко. Как правило, пользователь интересуется в документации тем, что нужно решить именно ему, и не замечает таких «недостатков». Задача техрайтера — предоставить пользователю полезную информацию.
Я так спокойно об этом говорю, потому что продукт — живой организм, он постоянно меняется.
Иногда, например, встречаются сюрпризы с наименованием элементов продукта. Работают себе две команды параллельно, или одна пришла сразу после другой. Они что-то создали, и каждый назвал «что-то» по своему усмотрению. Например, одну и ту же кнопку одни подписали Add, а другие — Create. Вроде и небольшая проблема. Но, во-первых, я за консистентность, а во-вторых, между этими двумя глаголами большая разница. В таком случае я предлагаю командам договориться и остановиться на одном названии, добавляю им объяснения со ссылками на словари, в чем же разница.
Я веду небольшой внутренний канал для команд в Slack, куда могут подписаться все в компании, кому интересно. Там рассказываю о грамматических и стилистических деталях, привожу примеры лучших практик для написания технической документации.
Пример рекомендации о разнице слов
Также стараюсь помочь продуктовым командам WePlay Esports и TECHIIA: создала для них отдельный гайд о стиле, аббревиатурах, грамматике и тому подобном. Это простые и короткие заметки, чтобы они могли проверить себя, если есть необходимость.
Очень плохая документация. Труднее работать с документацией, которую уже написал кто-то до тебя. Иногда из документации выглядывает «кошмар» как по структуре, так и по наполнению. Вероятно, этому есть объяснение, но не стоит тратить время, чтобы в нем разбираться.
Часть документации может оказаться полезной. Поэтому обычно я все оставляю без изменений, а возвращаюсь к критически важным статьям и немного их привожу в порядок только при необходимости. Какие из них являются критическими, можно понять в процессе пользования продуктом. Такую документацию переписываем, адаптируем под имеющийся стиль, что-то отправим в архив. Выделите на работу с уже написанной документацией год. Да, это действительно долго: частичный аудит, отсеивание «кошмаров», архивирование некритических статей (лучше иногда описать все снова).
Иногда компания хочет сохранить предыдущие версии документации, чтобы показать эволюцию продукта. Но даже для этого процесса нужно иметь инструкцию, как и что архивировать, вести версионность и тому подобное. Конечно, это задача техрайтера — нужно иметь целую стопку собственных внутренних правил и стандартов.
Если перед вами стоит выбор между созданием документации с нуля и всем, что я только что описала, советую отдавать предпочтение первому варианту. Есть определенное удовольствие в том, чтобы из ничего создать целый мир документации. А вот разгребать авгиевы конюшни — сомнительная радость.
Совет. Если у вас много команд и много продуктов, можно попробовать применить принцип CI / CD (continuous integration / continuous development). Возможно, даже к работе с документацией, которую создали до вас.
Я подслушала эту историю у своего коллеги Дэвида Бейли: он предлагает научить продуктовые команды создавать их документацию уже на местах. Задача техрайтера здесь — контролировать процесс, дать рекомендации, стандарты, проводить постоянные тренинги, консультировать точечно в вопросах, которые вызывают сомнения.
Документация готовится не единоразово на определенном этапе создания продукта, а проходит весь цикл его жизни. Таким образом она становится содержательнее, несет больше полезной информации
Выбор инструмента для написания документации. Здесь речь пойдет именно о райтерских инструментах.
Прежде чем что-то покупать, нужно долго поработать со своей документацией, понять, как вы пишете, храните, публикуете готовую документацию, какие у читателя требования и потребности.
Прежде чем приобрести свой инструмент, я все попробовала: практически по месяцу пользовалась различными программами, провела несколько демо. Затем всю информацию собрала в таблицу, разобрала достоинства и недостатки и в результате остановилась на MadCap Flare.
Если будет запрос, расскажу, как и среди чего выбирала — преимущества, недостатки, собственные соображения по каждому протестированному инструменту. Напишите об этом в комментариях.
Скрин программы MadCap Flare
И вот счастливая я переношу всю документацию в MadCap Flare. Здесь мы делаем следующее:
- пишем абсолютно все статьи — их мы тоже публикуем в Confluence для продуктовых команд, а еще это некий «бэкап» информации;
- централизованно создаем стиль и форматируем тексты (обычно это форматы PDF, HTML5)
- ведем свой глоссарий с определениями;
- обязательно поддерживаем «переменные» — как правило, это имена, которые мы вводим с помощью глоссария. Их можно удобно из одного источника заменить во всех мануалах, если вдруг возникнет необходимость;
- обязательно для работы в таком инструменте есть специальный гайд, который определяет все критические вопросы: стиль, грамматика, работа с визуализацией и тому подобное.
Рекомендации для начинающих
В нашей части мира техрайтерство — еще молодая профессия, она только формируется. Иногда на различных IT-ресурсах даже нет такой категории, чтобы отфильтровать по вакансиям или посмотреть статистику по зарплате. Поэтому трудно найти «отраслевые» стандарты, а каждый техрайтер может экспериментировать на свой страх и риск.
Первый совет — искать лучшие практики, читать мануалы компаний с историей и репутацией. У них техрайтерская традиция давно сложилась. Там работают целые отделы, вооруженные своими внутренними стандартами и политиками. Каждое их решение для документации давно обосновано, логично. Ты как машина — пишешь то, что сказали, и так, как написано в инструкции. В этой ситуации нет места для собственного видения, но именно за такими компаниями советую подсматривать в поиске своего стиля.
В качестве примера приведу . В частности, подробное относительно употребления слов.
Google еще и предлагает интересные курсы по техрайтингу для разработчиков, но они будут полезны всем: ;
Второй совет, который уже звучал, — сначала разобраться в продукте, сформировать архитектуру документации, создать свои стандарты и прописать для себя правила ее написания.
Меня иногда просят: покажи, как у тебя. Во-первых, не все можно показывать. Если документ не содержится в открытом доступе, скорее всего, он конфиденциальный. Во-вторых, пользы от этого никакой — другому техрайтеру это не поможет, потому что у каждого свои пользователи и они имеют собственные нужды. Просто «списать» не получится.
Третий совет — не копировать, а искать собственный подход. Работать на рынке с формирующейся техрайтерской традицией — самому участвовать в формировании правил игры. И в этом есть свои маленькие радости.
Маленький тест на определение техрайтера
В завершение хочу сказать, что не все так страшно. Работа с документацией — интересная, если ваши душа и мозг настроены на структурирование любой входящей информации. Но если человек считает себя техрайтером только потому, что умеет писать на английском языке, — должна разочаровать. Наша профессия довольно скучная, нужно уметь усесться и детально разобраться с продуктом; требует много усилий и времени на саморазвитие, а это непрерывный процесс.
Хороший техрайтер — тот, кто обращает внимание на детали и ищет возможность задокументировать должным образом что угодно. Например, как сделать скриншот со Smart TV без специального устройства? Хорошо, если вы работаете в Samsung и в ваших руках есть множество инструментов. А тем, кто подумал о фото экрана телевизора, сделанное на телефон, пока отказано в доступе в мир инструкций, гайдов и мануалов.
Если вы читаете инструкцию к новому гаджету, замечаете недостатки и хотите ее переписать прямо сейчас — вы прошли тест на техрайтера! Велкам в наше комьюнити.
Добавлю здесь свои любимые READ MORE. Список можно продолжить — эти ссылки только для вдохновения:
- ;
- ;
- ;
- ;
- .
Оригинал статьи на .
