Я пять лет разрабатываю техническую документацию. Всё это время руководящими документами были и ГОСТы групп 2, 7, 19 и 34, и разная экзотика вроде приказа Минпромторга № 4091 от 15.12.2015. Руководящие документы облегчают жизнь, сводя необходимость думать к размышлению о содержимом документа, а уж структуру и оформление диктует стандарт. Однако есть и сложности. Следуя стандартам, получишь стандартный документ, однако стандартный не значит удобный для чтения и исчерпывающе полный. Средства разработки документации — обычно это текстовые процессоры из офисных пакетов — требуют большой подготовительной работы по наруливанию стилей и организации рамок, чтобы привести результат работы к стандартному виду. Если же подготовкой пренебречь, через полсотни страниц документ станет технически неуправляемым. Наконец, прохладное отношение разработчиков к документации приводит к тому, что её разрабатывают или по остаточному принципу, или так, чтобы принял заказчик. Заказчик же в первую очередь ориентируется на критерии нормоконтроля, отнюдь не задумываясь о мере, в какой документ пригоден для чтения и понимания людьми.
Итог не обнадёживает. Значительная часть работы состоит из борьбы с условным Вордом, особенно если над документом работают несколько людей. Документы в результате получаются формально правильные, но часто не в мире читателя. У технического писателя остаётся ощущение, что он делает бесполезную работу.
Представился случай разработать технический документ на основе ценностей, противоположных перечисленным выше. Об этой работе и пойдёт речь.
Понять задачу
Задача была поставлена предельно просто: написать руководство пользователя для андроидного приложения HF Pager. Вскоре после начала переговоров решено было сделать бумажное руководство.
Руководство пользователя для андроидного приложения само по себе невероятная редкость — я сходу не смог вспомнить ни одного примера, тем более на бумаге. Затея сделать печатное руководство пользователя приложения на смартфоне нетривиальна, однако здравое зерно в этом есть. Бумажная документация не требует энергии и интернета, может быть продана как материальный предмет или предъявлена окологосударственным пользователям. Наконец, при должном подходе к печати бумажная документация солидно выглядит. Как бы ни была изготовлена документация, главная её задача — уменьшить нагрузку на хелпдеск. С этим соображением я и подошёл к делу.
Годное руководство пользователя — это ясная структура и необходимая достаточная полнота изложения.
Структуру рационально строить исходя из того, что любое содержимое руководства пользователя представляет собой либо решение задачи (таск), либо справочную информацию (референс), либо условно факультативные сведения для понимания происходящего под капотом (концепт).
Таск — отвечает на вопрос «Как сделать?». Чтобы заполнить этот раздел, нужно выписать себе список возможных задач пользователя, потом отранжировать разумным способом, а дальше при помощи чувства прекрасного оформить в пункты руководства. Список задач пользователя сложности не представляет: задачи — внешние по отношению к объекту документирования, и существуют в терминах действий пользователя. Залезть в меню — это не задача, а вот передать сообщение — задача. Ранжирование задач тоже несложно: в случаях вроде моего годится хронологический порядок возникновения задач по ходу эксплуатации.
Референс — отвечает на вопрос «Что это такое?». Подход схожий: выписать сущности, каждую пояснить, и ни слова сверх того. Порядок изложения сущностей — хронологический, от общего к частному, от очевидного к неочевидному, сверху вниз слева направо. В этой работе самое сложное — каждый раз вовремя остановиться. В моём случае референс состоит из двух уровней. На уровне оперативной справки для быстрого знакомства — картинки с основным экраном приложения с минимумом пояснений. Уровень детальной справки посвящён меню. Референс по меню написан преимущественно текстом, структура описания пунктов меню везде одинаковая: что это такое → что делает → значение по умолчанию. В отдельных местах я счёл целесообразным добавить ремарки в виде единообразно оформленных замечаний («Не трогай тут ничего») или советов («Прикрути фитиль, если по умолчанию слишком ярко»). Оформление придумал сам и вынес в раздел типографских соглашений, где ему и место.
Концепт — на вопросы не отвечает. Задача концепта — научить, показать общую картину, углубить понимание действий с объектом документирования. В моём случае этот раздел начался с малого, наполнялся постепенно, и в итоге превратился в самый объёмный по количеству текста. Сформулировать этот текст, и отбросить из него всё ненужное, тоже оказалось сложнее всего.
Информацию я решил сгруппировать по классам: после вводной информации дать решения типовых задач пользователя, потом справку по интерфейсу, а потом отдельно всё, что относится к концепту. Логика в этом решении следующая: приложение по умолчанию настроено достаточно правильно, чтобы сразу начать работать с ним, поэтому в справку по интерфейсу пользователь пойдёт только если что-то будет непонятно, а в раздел с концептами — из любопытства. Стало быть, что нужнее, то и ближе к началу.
Когда был готов проект большого руководства, внезапно оказалось, что нужно ещё одно, маленькое — quick start guide, руководство по быстрому старту, или просто РБС. Дело в том, что приложение предназначено для эксплуатации в полевых условиях без интернета, поэтому нужна шпаргалка по приложению, чтобы носить при себе. Требования к РБС те же, что и к руководству пользователя — ясная структура и полнота изложения. Из условий эксплуатации РБС следует ещё эргономические требования. На эргономике позже остановимся подробнее.
Структура РБС затруднений не вызвала: в РБС входит лишь то, что пригодится в полевых условиях. Поскольку задачи условно делятся на рабочие и служебные, оставить нужно только рабочие. Референс — на минималках, концепт не нужен. В итоге из руководства пользователя в РБС остались только три задачи, императивная справка по настройке, краткая справка по устранению неисправностей, и два чеклиста: один перед выходом на маршрут, другой — перед сеансом связи. Переиспользование контента наше всё, поэтому решения задач переехали в РБС без изменений, а вот справки и чеклисты я написал «с нуля».
Технология
Выбор средства производства «документа, содержащего в основном сплошной текст», не самоочевиден. Исходные предпосылки выбора таковы:
документ предназначен для печати, но потом может потребоваться электронная версия;
подход doc as a code по сравнению с традиционным более громоздкий, но облегчает переиспользование контента;
работать придётся с текстом и картинками, притом много и гибко;
на сказанное в ГОСТ 19 ориентироваться не надо;
Микрософт Ворд для серьёзной и тонкой работы с текстом неудобен, его аналоги тоже.
Поэтому на роль средств производства я выбрал VS Code для текста, Adobe Illustrator для картинок, и Adobe InDesign для создания непосредственно документа. Применять именно этот софт не обязательно: другие текстовый блокнот, векторный редактор и DTP-система способны решить ту же самую задачу. Текстовый блокнот, в отличие от текстового процессора, легко интегрируется с системой контроля версий — со вытекающими из этого удобствами работы с текстом. Необходимость векторного редактора для технической иллюстрации в пояснениях не нуждается. Для оформления текста в документ DTP-система лучше условного Ворда настолько же, насколько для резьбы по дереву стамеска и нож лучше чем топор-колун.
Отдельно поясню про формат текста: я выбрал обыкновенный неформатированный текст, а не маркдаун или ReST. Выбор формата в таком деле всегда компромисс: простой текст проще писать и читать, но сложнее конвертировать и переиспользовать автоматически, обратное тоже справедливо. В моём случае ключевым фактором стало взаимодействие с Индизайном: простой текст просто вставляется в текстовый фрейм прямо из буфера обмена. Это не лучший способ: можно было прилинковать текст к фрейму, и тогда бы макет автоматически обновлялся при правках текста. На больших документах лучше так и поступать, на небольших — можно обойтись и копипастой.
Индизайн прекрасен, но есть нюанс
Обратная сторона гибкости DTP — сравнительно трудоёмкое обновление документа в тот момент, когда от заказчика работ приедут серьёзные правки в текст. В этот раз правки приехали уже на этапе окончания вёрстки, и немедленно оказалось, что добавить короткий раздел в самое начало свёрстанной страницы нельзя, если не перебрать вручную вообще всё до следующего раздела. Конечно, есть прекрасные средства автоматизированной подготовки документации, умеющие в CI без участия оператора ЭВМ, но прежде уже было решено не оглядываться на ГОСТ 19, поэтому закат солнца каждый раз пришлось делать вручную.
Избежать этого не представляется возможным. Не получится сделать как в газете — волевым решением зафиксировать текст до вёрстки и потом не принимать никакие правки кроме исправлений опечаток и ошибок. В газете этот подход работает за счёт того, что тексты перед вёрсткой вычитывают сам журналист, выпускающий редактор, ответственный секретарь, корректор, и иногда ещё главный редактор. Поэтому в газетную вёрстку попадает текст заведомо вычитанный и согласованный. Для фрилансера этот путь не слишком надёжен: в переговорах с заказчиком на тему фиксации текста исполнитель явно не с той стороны ружья. Правильно воспринимать такие ситуации помогает знание о том, что покупают не текст, и даже не документ, а его полезное действие. Технически проблема решается так: можно оставлять на странице заделы под расширение, новые тезисы начинать с новой страницы, а новый раздел всегда с правой полосы. В крайнем случае помогает тонкий тюнинг текста как массива символов: в отличие от текстового процессора, нормальная DTP-система это умеет.
Инструкция по оригами
Выше я отметил, что РБС физически представляет собой лист бумаги, защищённый ламинацией или пластиковым пакетом, и свёрнутый дважды пополам так, чтобы получалось 4 маленьких страницы для информации первоочередной важности, и на обороте ещё столько же для относительно второстепенных сведений. Изобразить это в Индизайне не составило труда: фреймы с текстом легко поворачиваются на нужный угол. Чтобы разобраться с ориентацией фреймов на листе, согнул из листа бумаги макет.
Затруднения предсказуемо обнаружились сразу: первое же тестирование РБС на добровольцах показало, что они не понимают, как его правильно сложить. Неправильно сложенный лист катастрофически неудобен в использовании.
Разумеется, я с самого начала предусмотрел две линии сгиба и две стрелки с номерами, и конечно же, это не помогло. Стрелки оказались непонятны никому, а нарисованные линии сгиба не совпали с фактическими, поскольку принтеры обычно печатают немного криво.
Пришлось искать другое решение. Для этого сформулировал критерии хорошей инструкции по оригами:
настолько однозначная, насколько возможно;
визуально заметная, но не бросается в глаза при дальнейшем использовании документа;
предельно короткая;
скорее длинная, чем широкая (высокая), поскольку на линию сгиба заложено всего 10 миллиметров;
императивно обращается к пользователю так же, как остальной документ, или вовсе не обращается.
Окончательное решение придумал с четвёртой попытки, остановившись на серых надписях жирным серым моноширинным шрифтом: «линия первого сгиба этой стороной внутрь», «линия второго сгиба — на противоположной стороне листа», «линия второго сгиба этой стороной внутрь». Существительные выглядят менее навязчиво, чем глаголы; моноширинный шрифт подчёркивает специальное предназначение надписи и несколько купирует эффект близости, благодаря которому объекты, расположенные ближе друг к другу, выглядят сильнее взаимосвязанными.
Вероятно, идеальное решение — организационное: централизованно отпечатать и согнуть как надо.
Нам всем мешает знание
Техническая документация подразумевает баланс между тем, что в ней есть, и тем, чего в ней нет, и удержаться в балансе ещё нужно суметь. Если недописать нужного, документация не принесёт пользы, итогом чего станет вал однотипных вопросов к хелпдеску, а у заказчика появится справедливое недоумение по поводу уплаченных за документацию денег. Если же переписать лишнего, то можно в лучшем случае нарваться на необходимость поддержки чужих продуктов, а в худшем — хелпдеск будет отдуваться не только за софт, но и за документацию.
Описать сбалансированно таск или референс относительно несложно: таск — о том, что пользователь делает; референс — о том, что пользователь видит и нажимает. В обоих случаях абсолютно необходимый объём изложения и есть достаточный. Иначе дело обстоит с концептами: они посвящены тому, что пользователь не знает.
Это ключевой момент: когда для автора всё понятно, как автору понять, что не знает пользователь? По логике™ — спросить об этом у самого пользователя, а ещё вернее, сделать так, чтобы пользователь сам об этом рассказал. Сам пользователь рассказывает исключительно хелпдеску или тому, кто за него — например, знание о незнании я почерпнул в чате сообщества пользователей приложения.
Так в разделе концептов появились четыре темы: объёмная «Организация радиосвязи», сложная и абстрактная «Однополосная модуляция», лёгкая «Выбор скорости манипуляции», и просто справочная «Использование маяка». Написать о том, как я решил задачу изложения этих тем, мне тоже мешает знание: я их просто взял и изложил. На это, однако, было израсходовано 2 дня времени и 6,5 тысяч знаков текста в тысяче слов, основной труд состоял в постоянном отвечании на заданный самому себе вопрос «Что реально надо знать пользователю об этом?»
Ответ лежит на поверхности: пользователю необходимо и достаточно знать то, что он сам спрашивал себе в помощь. Тут мне повезло: я несколько лет участвовал в переписке по работе приложения, и уже знал, что именно пользователь часто спрашивает. Поэтому, например, раздел «Однополосная модуляция» почти полностью посвящён вычислению в уме фактической частоты поднесущей.
Для незнакомых с радиотехникой поясню: это как если рассказ о Налоговом кодексе РФ свести к пояснению, как считать сумму к начислению заработной платы по величине выплаты «на руки».
Тему «Однополосная модуляция» лучше было бы пояснить картинкой. Так и предполагалось сделать, но возникла проблема: то главное, что нужно знать об однополосной модуляции пользователю приложения, оказалось очень сложно изобразить на неподвижной картинке так, чтобы читатель точно всё понял.
Усилием воли пришлось признать самому и убедить заказчика, что популярные в радиотехнической литературе картинки со спектрами для совсем неподготовленного читателя не годятся, и ничего не поясняют. Признать общепринятую иллюстрацию негодной требует смелости и умения в рефлексию. И таки да, это тот случай, когда знание мешает.
Можно было бы потратить пару дней на творческий поиск, и картинку в итоге сделать. Однако время поиска стоит заказчику денег, а вкладывать их в явно факультативный материал не слишком разумно. Поэтому картинку отложили на период гарантийной поддержки документа: за время гарантии можно в спокойном темпе придумать и протестировать на пользователях иллюстрацию, которая будет работать как следует.
Важные мелочи
Я сдержанно отношусь к ГОСТам, посвящённым документации, но эти стандарты избавляют от размышлений о том, как писать документ. Поэтому, отказавшись от следования государственным стандартам, пришлось придумать свой частный стандарт, и следовать уже ему. Формально я стандарт записывать не стал, но в голове сформулировал, что он регулирует:
— структуру документа;
— язык и стиль;
— логику оформления;
— общий подход к подготовке иллюстраций.
То есть, в принципе, всё то же самое, что ГОСТы 19.106 и 19.505, но с человеческим лицом.
Одной структурой в техническом документе не обойтись, нужна ещё навигация. Для навигации по документу использованы колонтитулы и оглавление с нумерацией страниц, а для навигации по странице — типографика. Колонтитулы не повторяют заголовки, и названы обобщённо по тому, какого рода материалы под собой они объединяют. Перекрёстные ссылки, в том числе на рисунки, также ссылаются просто на номера страниц. Это стало возможным благодаря тому, что каждый рисунок, на который в документе есть ссылка, на странице ровно один. Остальные рисунки расположены по принципу близости к абзацам, в которых они упоминаются, поэтому удалось приемлемо обойтись без подрисуночных подписей с нумерацией рисунков. Абсолютное большинство рисунков без подписи собрано в разделе справки по интерфейсу, и ссылаться на такие рисунки не нужно.
Типографские соглашения также основаны на визуальном восприятии. Жирное начертание выделяет текст, требующий первоочередного внимания. Курсивное начертание визуально прозрачнее прямого, поэтому курсивом обозначены факультативные советы, нужные для более связного понимания написанного. Также советы и примечания обозначены буллитом, сделанным из логотипа приложения. Отдельные примечания даны сносками. Сноски выглядят совсем ненавязчиво, хотя и появились скорее потому, что добавить их в готовую вёрстку ничего не стоит — перевёрстывать страницу не нужно, а текст в сноске умещается довольно длинный. Сноски как разновидность примечаний в руководстве пользователя стилистически избыточны, однако в моём случае удалось соблюсти некоторую консистентность: в отличие от императивных советов, сноски просто что-то поясняют.
В нижний колонтитул руководства пользователя, кроме номера страницы, влезла ещё строка с номерами версий документа и приложения. Оба номера важны, поскольку документация обновляется отдельно от приложения. В РБС нумерация страниц не нужна, и строка с номерами версий расположилась там, где для неё нашлось место. Стили оформления РБС и руководства пользователя не идентичны, поскольку условия чтения РБС отличаются от условий чтения руководства пользователя.
Тестирование документации и обратная связь
Документация — такой же продукт, как и то, что она документирует, поэтому тоже подлежит тестированию. В моём случае тестирование прошло прямо на пользователях: РБС и руководство пользователя заказчик зарелизил прямо в чате поддержки приложения, и через полчаса туда посыпались отзывы. Большинство — с благодарностями, но нашлись также энтузиасты, высказавшие по существу. Один из них вовсе написал целый протокол разногласий объёмом 5 страниц. Несмотря на то, что критика почти не повлияла на содержимое документов, руководство пользователя обновилось три раза. В документах нашлись помарки: например, я неправильно настроил форматирование перекрёстных ссылок, из-за чего образовались лишние слова, и вёрстка расползлась. Ещё пришлось изменить отдельные формулировки: в одних уточнили смысл, в других улучшили читаемость.
Значительная доля замечаний коснулась достаточной полноты изложения. В чате приложения неделю кипел такой обмен мнениями в таком духе:
Почему бы не написать, какие разрешения дать приложению?
Потому что точный список необходимых разрешений меняется с каждым новым Андроидом, а перечислять и даже просто узнать конкретные разрешения нет ни смысла, ни возможности. Надо просто дать все запрошенные разрешения.
А почему не сказано, что надо включить режим VOX на радиостанции?
Потому что есть радиостанции без этого режима, а сопряжение смартфона с радиостанцией зависит от модели и смартфона, и радиостанции.
Почему нет раздела о настройке однополосной модуляции?
Потому что область определения руководства пользователя — приложение, а не сопряжённая с ним радиостанция.
А перенесите раздел «Ограничения демо-версии» в раздел «Регистрация приложения»?
Нет, потому что регистрация — обязательная операция для всех, а вот ограничения демо-версии — информация справочная, и нужна она только тем, у кого демо-версия есть, а это вообще отдельное приложение.
Добавьте, что в однополосной модуляции принято работать верхней боковой полосой в цифровых режимах?
Нет, потому что у нас не руководство по радиосвязи.
Может показаться, что пользователей послали. На самом деле это не так. Область определения документа, структура и достаточная полнота содержания — это то, что ограничивает документ в интересах пользователя. Если его запросы выходят за пределы области определения, значит, нужно просто написать ещё один документ.
Замечания к тексту разделились на два класса: замечания к структуре и содержанию, и замечания к формулировкам. Различаются эти классы тем, что замечания к формулировкам изменяют смысл сказанного, а замечания к структуре и содержанию — смысл дополняют, но не изменяют. Замечания к структуре и содержанию объясняет желание пользователей увидеть всеобъемлющее руководство по радиосвязи с помощью приложения. Такие замечания интересны для понимания того, как пользователи мыслят и читают, но переносить их в документацию надо с осторожностью, иначе в попытке объять необъятное легко получить неподдерживаемую спагетти-структуру. А вот замечания к формулировкам ценны: если пользователь формулировку не понял, или понял неправильно — это проблема документации, которую нужно выявить и исправить. Радикально исправлять формулировки мне не пришлось, но три из них по предложениям пользователей я уточнил.
Резюме
Стандарты рулят. Использовать или не использовать ГОСТ — зависит от ситуации. Если необходимости неукоснительно соблюдать ГОСТ нет, то неплохим решением будет разработать свой стандарт оформления и структуры, или использовать любой готовый понравившийся стайлгайд. Дизайнером для этого быть не обязательно: достаточно ознакомиться с фундаментальными принципами из книги «Дизайн для недизайнеров» Робин Уильямс, а для самого начала можно взять за образец даже стили по умолчанию в Ворде.
Независимо от используемого стандарта важна структура и документа, и повествования, притом единообразие структуры важнее её устройства. Утверждение это может показаться банальным, но проблемы со структурой случаются чаще, чем хотелось бы.
Техпроцесс с раздельными подготовкой и оформлением текста показал себя целесообразным и оправданным при создании печатного документа. Текст потом легко будет перенести в электронную справку, его удобно хранить на гите, и вообще разделение контента и оформления — затея правильная.
Обратная связь и тестирование документации тем важнее, чем шире круг пользователей, и чем меньше команда, силами которой можно выявить проблемы до релиза. Мой случай почти экстремальный: один разработчик, один заказчик, один писатель, и пользователи самых внезапных уровней квалификации. В идеальном случае документацию на пользователях тестировать не следует, но собирать у них отзывы о документации полезно: так можно понять, какой информации пользователям не хватает, и в каком документе её можно изложить.
Постскриптум. Цена вопроса
Исследование софта заняло 20 часов: скачать, установить, зарегистрировать, проверить все режимы работы, найти ограничения, всё непонятное — выпытать у разработчика. Картинки заняли 10 часов: скриншоты сделать, недостающее отрисовать и поправить столько раз, сколько потребуется. Буллит для выделения комментариев, например, удался с четвёртой итерации. Два осмысленных и проверенных текста общим объёмом 28 тысяч знаков заняли 40 часов. Вёрстка — 15 часов. Правки, шлифовка, полировка, и шабрение текста — в совокупности ещё 20 часов. Итого 105 часов учтённого рабочего времени, и какое-то количество неучтённого.
Работа над этим руководством не завершена окончательно: до конца 2023 года продолжается гарантийный срок, по мере обновления приложения придётся обновлять и документацию. Это будет уже другая история.