Давным-давно, когда компьютеры были деревянными, жил-был один добрый инженер. Тогда инженеры все были добрыми — это была престижная работа, хотя никто и не знал ещё слова «престижная». Однажды, переписывая в десятый раз сложнейшую программу (весом в 4 килобайта), он вдруг подумал: «А пошло оно всё!». Встал, написал заявление по собственному и ушёл торговать контрафактными джинсами… Ой, простите, это из другой истории про другого инженера. Наш ничего не писал. Ну то есть писал, конечно, но не заявление, а программы. Хотя и заявления иногда тоже — на отпуск например. Или на отгул вне очереди, когда его собака ощенилась на даче, а жена не знала, что делать. Ему тогда не подписали заявление, и жена (суровая работница общепита: столовой при трубопрокатном заводе) утопила всех щенков, потому что маленькие дворняжки никому не нужны, а в однушке на 34-х метрах не уместишь шесть здоровенных псин. Дача-то только летом, да и то по выходным.
В общем, да, грустная тогда вышла история. Инженер наш даже запил немножко. Недельку. Его бы уволили, но на предприятии никто не знал, в какое место надо засовывать перфокарты — и его оставили, просто лишив премии. Но премия была небольшая, так что он не сильно и расстроился. Вообще, зарплата инженера тогда была не ахти, не то что сейчас. Хотя тогда и цены были другие. А вот продуктов не было — один только дефицит в каждом магазине. Инженер вообще был доволен, что нашел такую жену, которая в общепите работает. Сами понимаете, о таком писать не принято, но с едой у них в доме проблем не было. Мурзилке (это собаку так звали, которая на даче ощенилась, из-за чего инженер пытался взять отгул, но ему не дали и он запил) вообще повезло — жена (инженера, не Мурзилки) каждый день что-нибудь, да и приносила с работы.
Это — история
И она не про Мурзилку, не про инженера с женой и не про расхищение социалистической собственности. Эта история про проектирование.
Хотя так себе история, надо признаться. Да что там, чушь полная. Хотел поведать о том, как нелегко было инженеру в ту пору сформировать архитектуру даже простой программы, но в какой-то момент… Что произошло вообще? Да все просто: мелочи, детали и нюансы погребли под собой суть. Причем так ловко, что та даже опомниться не успела.
У рассказа должна быть структура, иначе крайне высок риск, что он превратится вот в такую вот ахинею. Только профессиональный писатель способен удержать план длинного рассказа в голове, да не растерять при этом хотя бы те же характеры персонажей. Поверьте, это сложнее, чем даже оправдываться перед женой, которая винит тебя в том, что утопила пятерых щенят.
Примерно такая же ситуация возникает и при попытке сформировать/сформулировать требования к разработке ПО. Вы можете быть суперкрутым спецом в своем деле, но если вас ненавидит проектная команда, какой в этом прок? А если ей придётся продираться через сбивчивый документ в 300 страниц — она вас возненавидят, гарантирую.
Все делают это
Проектную документацию, в том или ином виде, пишут все дизайнеры. Однако качество подобных творений такое же разное, как и уровень самих творцов. И я говорю не только о содержательной части.
Плохая проектная документация — как арт-хаусное кино: кто-то поймет, кто-то нет, а кто-то только подумает, что понял. Разница лишь в том, что выяснить, к какой из этих категорий относится исполнитель проекта, получится только в самом финале. И вам очень повезет, если в финале проектирования, а не реализации.
Когда ты создаёшь дизайн продукта, ты словно пишешь рассказ (а иногда даже почти книгу). А чтобы написать художественное произведение, недостаточно просто пересказать историю. Нужно понимать характер персонажей, знать предметную область, понимать, кто именно твои читатели, и много чего ещё.
Нафига писать рассказ, который никто никогда не прочтёт? Или прочтёт с явным трудом, как инструкцию к старой микроволновке? Рассказ должен читаться легко, оставаться в памяти надолго, читатель должен жалеть, что рассказ кончился. Так и с документацией.
О боги, сколько я за свою жизнь видел техзаданий, концепций и диаграмм, которые никто, кроме их создателя, не может прочесть! А спустя полгода-год — уже и сами создатели с трудом их осиливают. Такая документация становится «вещью в себе», она существует вне нашего восприятия. Не надо так делать.
Видите картинку сверху? Она создавалась Мариной Пустовит с целью структурировать у себя в голове всю имеющуюся информацию по данным проекта. Такие запутанные схемы ни в коем случае нельзя передавать разработчикам и, тем более, клиентам. Мир и так не идеален, не стоит делать его хуже, а людей — грустнее.
Помните, что у проектной документации тоже есть пользователи. Рассматривайте её как отдельный внутренний продукт.
Ваша документация должна быть понятной, однозначной, отчуждаемой. Она должна быть, чёрт возьми, интересной! Это ведь действительно не очень сложно. Мы придумываем удобные интерфейсы (и не важно, UI или API) — но даже не пытаемся понять тех, кто реализует то, что мы там напридумывали.
Статья называется «учим проектную команду читать», но, говоря по правде, она должна называться «учимся писать для проектной команды». Или «прививаем проектной команде любовь к чтению». Ведь сложно полюбить чтение, если вся твоя библиотека — это учебники по ядерной физике и селекции папоротниковых (хотя тут на любителя, конечно).
8 советов
В итоге я собрал несколько правил и хаков, упрощающих «впитывание» информации членами проектной команды (да и клиентами, чего уж там).
Часть из этих советов я подсмотрел у других дизайнеров, часть выработал сам, а часть всплыла в ходе моего недавнего микро-опроса на фэйсбуке (за что отдельное спасибо Астхик Сукиасян, Антону Григорьеву и Виталию Мазуревичу).
Разумеется, это никакой не чеклист. Используйте только те пункты, которые применимы к конкретному проекту и конкретным условиям. Включайте голову, в общем.
Плавное погружение
Самый важный пункт по версии моей бабушки.
Серьёзно, нет ничего хуже, чем с ходу бросать несчастных читателей в дебри CJM и фронтенд-спецификаций. Особенно, если проект сложный и документация по нему подробная. Мотивация к дальнейшему чтению убивается надёжнее, чем микробы сейфгардом.
Делайте погружение в документацию плавным. Сперва расскажите основную информацию о проекте: краткое описание, задачи, ЦА, ключевую механику. Опишите базовые компоненты, состав сервиса, какие-то особенные технические или бизнес-требования. Очертите границы проекта.
У меня даже есть специальное слово для такого «вводного» документа — концепция. Обычно это небольшой документ на 3-4 страницы (зависит от сложности проекта) с очень чётким оглавлением и содержанием. Иногда уже одного этого хватает, чтобы тот же разработчик задал вам потом в миллион раз меньше вопросов. А уж клиенту/заказчику этот документ необходим как воздух.
Современные инструменты
Перестаньте использовать MS Office и файлики с макетами. Мир прекрасен и удивителен — и в нём есть куда более гибкие и подходящие для документации инструменты.
Интерактивные схемы, встраивающиеся прямо в страницы с текстом; перекрёстные ссылки на разделы; макросы и динамические содержания конкретных частей; краткие выжимки из разделов — это и многое другое откроется вам, как только вы начнёте использовать современный инструментарий. Просто представьте себе, насколько приятнее (и быстрее) нажать на статическое изображение и сразу открыть интерактивную user story, чем прочитать что-то вроде «более подробно схема представлена в рис. Польз_история_1_ (версия_5).jpeg в папке user_stories на Google Drive».
Хороших инструментов много, никто не мешает вам их совмещать и комбинировать, пока не найдёте идеального для вас варианта. Я лично предпочитаю Confluence (с десятком полезных плагинов) в связке с Axure и Figma. Но иногда не пренебрегаю и обычными гуглдоками (если их правильно приготовить, конечно).
Структурирование
Есть одна простая штука: в проектной документации нарратив не работает. Если у вас проект чуть сложнее лендинга, то разработчик (маркетолог/сеошник/клиент) будет скакать по разделам, как кузнечик по углям. Дайте ему возможность делать это легко и естественно.
Чёткая и (главное) понятная структура документации — залог её эффективного использования. Причём это касается как самих документов, так и разделов, в которых они лежат.
Пользователь (мы же помним, что у документации тоже есть пользователи, да?) должен иметь возможность найти любое место в доках буквально за 5 секунд.
Вот так выглядит примерная структура разделов у меня в Confluence (первые два уровня):
- Roadmap
- Текущее состояние
- Требуется уточнение
- Требуется проработка
- Требуется локализация
- TODO
- Следующие итерации
- Словарь терминов
- Концепция
- Компоненты
- Мобильное приложение
- Сервер
- Админпанель
- Сайт
- UX/UI
- Аудитория
- Сценарии
- Навигационная модель
- Прототип
- Screen Flows
- Дизайн-макеты
- Entities
- Functions
- Fn.Mobile
- Fn.Server
- Fn.Admin
- Fn.Site
- API
- Философия API
- Словарь ошибок API
- API.Mobile
- API.Admin
- Databases
- Db.Mobile
- Db.Server
Разумеется, эта структура меняется от проекта к проекту — и об этом следующий пункт.
Контекст использования
Все команды и продукты разные. Если вы однажды нашли подходящий формат документации для одного проекта — не факт, что он станет таким же идеальным для другого.
Высокотехнологичные стартапы требуют более проработанной архитектуры, чем e-commerce на Битриксе. Команды, выполняющие типовые задачи (вроде того же e-commerce), наверняка уже знакомы с их базовыми UX-особенностями. Фрилансерам или удалёнщикам желательно расписывать всё максимально подробно — тогда как для остальных эта информация может оказаться избыточной.
Если у вас уже есть команда разработки, поинтересуйтесь, разные ли люди отвечают за фронтенд и бэкенд. Это позволит понять, нужно ли мешать серверную логику с клиентской — или стоит разнести их по разным разделам. Аналогично с дизайн-макетами сайта и мобильного приложения.
Учитывайте особенности проекта, а также кто и в каких условиях будет его разрабатывать и развивать. Использовать один и тот же формат от проекта к проекту можно только в том случае, если вы стругаете однотипные сайты, а делает их одна и та же команда.
Унификация формулировок
Это как с элементами интерфейса. Каждый новый элемент заставляет пользователя немножко, но учиться. Когда элементы на разных экранах выполняют одну и ту же роль, логично сделать их одинаковыми.
Если где-то вы написали «проектируется в следующих итерациях» — используйте эту фразу везде, где речь идёт о фичах, которые нужно продумать и описать при развитии продукта. Кроме того, что это будет удобно для читателя, это позволит вам потом простым поиском по документации собрать всех этих «ждунов» в одном месте. А не вычитывать внимательно сотню страниц. Посмотрите в структуру выше, там есть раздел «Текущее состояние» — вот он как раз и собирает такие штуки. Причём делает это автоматом и динамически.
Словарь терминов
Незаменимая штука при соответствии любому из двух условий:
- в проектной команде меняются люди;
- проект необычный или сложный;
В первом случае это не обязательно обусловлено текучкой. Если проект долгий, менять разработчиков раз в квартал/полгода — нормально, защищает от выгорания. Имея словарь терминов, вы снижаете порог входа новых людей в проект.
Второе условие самое очевидное. Если проект связан, например, со специфической отраслью, типа налогообложения или нейрохимии, иметь такой словарь — значит увеличить шансы на правильное понимание всей документации.
Вообще, я бы рекомендовал заводить словарь терминов на всех проектах сложнее лендинга. А уж если вы научите свою документацию подсвечивать термины и выдавать определения, не сходя со страницы — спасибо вам скажут все: от разработчика до уборщицы.
Вот, например, специальный плагин такого словаря для Confluence.
Удобочитаемость
То, что сейчас принято называть «UX текста».
Разбивайте текст на абзацы, выделяйте важные места. Не пишите слишком длинных предложений, используйте переходные слова. Если где-то в проектной логике есть условия, делайте из них список (а лучше — диаграмму). Подзаголовки — наше всё.
И ради всего святого, не используйте канцеляризмы. Пишите простым языком, вы не на юридический поступаете.
Ну да на эту тему написано уже много, не стану повторяться. Если интересно, посмотрите на индекс удобочитаемости Флеша и индекс туманности Ганнинга — математика, конечно, но с неё можно начать.
Пасхалки
Обычно пасхалки используются для того, чтобы выяснить, читала ли вообще вторая сторона документ.
Когда был в агентстве, то вставлял в доку пасхалки. Например: при нажатии кнопки Звезда Смерти взрывается. Если я видел, что ТЗ согласовано с ними, то ловил на том, что его не читали. Однажды в ответ на такое ТЗ мне заказчик прислал правки, где фраза про Звезду Смерти была прокомментирована так: И Дарт Вейдер переходит на светлую сторону Силы.
Виталий Мазуревич
В случае, если вам надо замотивировать команду именно прочитать документацию, вы можете просто намекнуть им на наличие таких пасхалок. Даже если их там не было и нет.
Конечно, с этим нужно быть осторожным. Излишне азартные люди могут крайне рьяно искать скрытые послания в доках. Вместо того, чтобы изучать эти самые доки.
Завершение
Ну и в конце я отдельно хотел бы упомянуть про необходимость поддерживать документацию в актуальном состоянии на протяжении всего проекта или, хотя бы, до конца разработки. Ибо любая документация устаревает: у продукта появляются новые микро-фичи, бизнес решает нацелиться на другой сегмент, а разработчики решают заюзать новую библиотеку. Однако не каждый дизайнер/проектировщик живёт на проекте так долго. Вот и получается, что спустя пару месяцев всё чаще звучат фразы типа:
Неактуальная документация может здорово снизить динамику разработки, а то и вовсе похоронить проект. Некоторые разработчики (заказчики/маркетологи) с радостью вернутся к привычному состоянию — когда можно было не читать.
Но это уже другая история, не про Мурзилку, её хозяйку и их мужа-инженера (который ушел в недельный запой из-за того, что жена утопила пятерых щенков, хотя одного из них он обещал своему начальнику).
P.S. На картинке к посту кубики Чаплыгина, крайне рекомендую для тех, у кого дети учатся читать.
