Сегодня поговорим о том, как избавиться от документации, которая не работает, описывает какое-то легаси, не организована, не соответствует идентичности вашего бренда, да что там — просто плохой документации. Чтобы затем подготовить и реорганизовать хорошую, валидную, логично организованную и соответствующую идентичности бренда документацию. И как только вы сможете избавиться от документации — все станет радужно и прекрасно.
Под катом перевод доклада Александры Уайт, технического писателя из компании Google, на конференции Write the Docs Prague 2018. А уже через неделю 26 апреля 2019 Александра выступит на нашей конференции KnowledgeConf с докладом «How to create compelling multimedia documentation». Александра расскажет, как встроить мультимедиа форматы (видео, аудио, gif) в процесс создания артефактов и упаковки знаний, когда мультимедиа форматы подойдут лучше всего, а когда не будут работать, как измерять эффективность мультимедиа артефактов и преодолевать их ограничения.
Для начала расскажу о себе, что и откуда я знаю. Меня зовут Александра Уайт, я живу в Нью-Йорке, я технический писатель, а до этого работала веб-разработчиком в телевизионной компании. Там люди работали по 5, 10, 15 лет в окружении большого количества легаси-информации о том, где код лежит и как работает.
Было очень сложно приступить к работе, найти какую-либо информацию, приходилось бесконечно задавать вопросы инженерам. На это тратилось немало времени, поэтому я начала пропагандировать комментарии в коде, написание актуальных readme, а впоследствии это стало моей работой в облачной компании Joyent.
Когда я пришла в Joyent, я мало что знала про облачные хранилища: слышала основные популярные термины, была на одной конференции. Было бы странно рассказывать людям, как использовать наши продукты, когда я не имею понятия об этом. Поэтому мне требовалось «бежать в два раза быстрее». В течение следующих восьми месяцев я была единственным в проекте техническим писателем и редактором, раньше эти задачи выполняли инженеры, команда технической поддержки, менеджеры продуктов. Они делали максимум от них зависящего, но в рамках своих приоритетов.
Признаться, когда я пришла на проект, там царил хаос, тысячи документов, не организованных, не вычитанных. Я пыталась работать как можно быстрее, чтобы закрыть пробелы. Например, у нас не было вводной документации, как начать работать с контейнерами, чтобы начать работать с продуктом, это и стало моим первым вызовом. Я начала работать над вводными инструкциями по Docker для нашего основного продукта — Triton.
Наконец, когда удалось развязаться с этой срочной задачей, и, как мне кажется, я начать разбираться в продукте, я занялась любимым делом — начала «сносить» старую документацию.
Сегодня я расскажу, как это сделать, как разрушить старое и построить новое, чего это стоило, как я создала контент стратегию и стайлгайд, и, в качестве бонуса, расскажу, что делать, если обстоятельства находятся не на вашей стороне и появляются препятствия в работе.
А еще поделюсь тем, что не учла, когда начинала работать над проектом, чтобы вы, когда будете планировать работу, смогли сразу все сделать правильно.
В августе 2016 года, начиная работу над проектом, я провела аудит контента и была в ужасе, у нас оказалось 9 (!) разных сайтов с документацией. О большинстве из них я даже не знала в течение года работы. И не было ни одного описания того, как писать документацию, поэтому вам требовались или огромные усилия при поиске информации, или знать очень изощренные способы работы каждого из этих сайтов.
Кроме того, я обнаружила огромный технический долг, который возник из-за того, что кто-то опубликовал документ и забыл о нем, «оставив умирать».
Для начала, я покажу, сколько разных сайтов с документацией мне удалось обнаружить. Когда мне сложно найти нужную документацию, я использую поиск Google. Так что я скрестила пальцы и надеялась, что найденная информация будет правильной. Это было не лучшее решение, потому что многие из наших сайтов закрыты авторизацией.
Да что там, даже наши инженеры используют Google, чтобы найти нужную информацию о продукте. В этом кроется проблема.
Итак, первое хранилище — это вики, ее ведут системные операторы и команда поддержки. Из всей документации эта — наиболее актуальная, но она закрыта авторизацией, а поиск информации в ней был секретом команды поддержки, которым они не хотели делиться.
Еще одно хранилище — это тикет-трекер JIRA.
Там хранились разные баг-репорты, инженеры и члены команды поддержки описывали, как исправить данные баги, как решить тот или иной вопрос, но информация так и оставалась в этих тикетах, никогда не попадая в публичную документацию.
Также у нас был сайт с документацией на API, сделанный по технологии единого источника из исходного кода. Он классный, это именно то, к чему я стремлюсь — документация настолько близкая к коду, насколько это возможно.
Однако, на деле код обновлялся быстрее, чем документация, ему соответствующая.
Наконец, у нас был блог продукта. Вы, вероятно, скажете, блог — это же маркетинг, но нет, в нем публиковались весьма глубокие технические документы, описания интеграций и концептуальные обзоры, многие из которых были намного качественнее, чем наша документация. Кстати, вот и она.
Предполагается, что это основное место, где пользователи могут получить поддержку и понять, как наше облачное хранилище работает. Но, к сожалению, эту документацию поддерживала команда продукта, а не инженеры. Некоторые из наших инженеров вообще не знали о существовании этого веб-сайта. И, повторюсь, это публичная документация.
Итак, мы в ужасе. Нет никакого жизненного цикла документации. Документ опубликован — отлично, больше не нужно думать о нем, все с порядке. В этом и кроется проблема. Контент создан множеством разных, не похожих друг на друга голосов: техподдержки, инженеров, менеджеров по продукту, а не одним голосом Joyent. У каждого стейкхолдера свое мнение, свое видение того, как документ должен выглядеть и где его нужно разместить.
Кроме того, никто не тестировал этот веб-сайт, чтобы понять, как его читают пользователи, что на нем ищут, чтобы лучше понять, что именно им нужно.
Но любой хаос можно исправить, есть минимум два способа: привести в порядок или начать с начала.
Наша работа как технических писателей — помочь пользователям найти ответы на их вопросы, будь то решить проблему в минуту паники или найти какую-то мелочь, которая поможет использовать продукт более эффективно. А еще наша работа — помочь коллегам писать лучше. Мы не можем быть экспертами во всем. Мы полагаемся на subject matter experts — экспертов в определенной области, чтобы мы могли помочь пользователям знать то, что им НУЖНО знать.
Технические писатели — это пастухи. Мы ведем пользователей и коллег к ответам и практическим решениям. И иногда лучшее решение — начать с начала. Но после стольких вложений в существующую инфраструктуру, сжечь все до тла кажется рискованным для стейкхолдеров.
Важно понимать, что такое хорошие аргументы, и как они важны. Я поняла это еще в детстве.
Мы с моим братом очень хотели собаку, но папе казалось, что это тяжкое бремя. Так как же мне убедить моего отца, что собака — это полезный и нужный член семьи, а не просто животное, требующее вложений денег и сил.
Мы написали детальное обоснование, как появление собаки сделает нашу семью счастливее и как мы планируем разделить обязанности по ее кормлению, выгуливанию и уборке за ней. Мы предложили расписание и даже придумали, как планируем заработать денег на услуги ветеринара. Как видите, аргументы сработали. Мы завели чудесного мопса Мегги, она стала членом семьи.
Придумать аргументы для руководства, что работа по «сносу» документации заслуживает траты времени и денег, это уже половина пути к хорошей документации.
В конце концов, если вы не можете убедить руководство в этом, возможно, изменения вам и не нужны. Хороший аргумент — это написать проект будущих изменений.
Пишем проект для руководителя
Когда вы пишете проект, помните, что вы не ваша аудитория. Это маркетинговый документ, который говорит: «Эта работа важна, и вот почему. Вот так я планирую исправить наши проблемы, и вот такую прибыль это принесет компании».
Сам процесс написания проекта по перестройке документации поможет вам лучше понять задачу с практической точки зрения, понять проблемы, с которыми вы столкнулись, будь то отсутствие контента, неорганизованные документы, устаревшая информация или что-то еще.
Как я уже говорила, у нас был ряд проблем с документацией в Joyent. Но только потому, что я знала, что документация не в форме, не значит, что я могла игнорировать срочные нужды клиентов. Я не могла позволить себе роскошь прекратить отвечать на тикеты, пока составляла планы, поэтому мне приходилось также писать новые и улучшать старые документы. У меня не было возможности остановиться.
Однако, работа над проектом, чтобы убедить руководство, помогла мне затем исправить стратегические проблемы с документацией так, чтобы в будущем их было меньше.
Если вы не можете убедить менеджера в том, что изменения нужны, то вы вряд ли сможете что-то поменять и в документации.
Давайте посмотрим на мой проект, который помог мне получить ответ «Да» на предложение «снести» документацию.
Прежде всего, каждый успешный проект начинается с введения. Вы верно спросите, почему это важно? Если люди не осилят даже первую страницу, если вы не убедите их с первых строк, то уже не важно, насколько крутые аргументы вы предложите дальше. Сначала нужно донести до них, почему это проблема, почему она существует. Подготовьте читателя к тому, чего ему следует ожидать на следующих страницах.
В первой версии проекта я указала на тот факт, что у Joyent был длинный технический долг, давно пора было переделать документацию, и сейчас мы пожинаем плоды этого. Этого следовало ожидать, имея 9 разных сайтов с документацией.
Чтобы подкрепить аргументы, я начала рассказывать о целях компании, например, стать номером один на рынке облачных провайдеров, нежели нишевой компанией для гиков. Но просто писать «мы лучшие» в маркетинговых материалах, не достаточно для реализации этой цели, нужно рассказать рынку, как пользоваться нашим продуктом. Если никто этого не знает, то не важно, насколько крутой продукт вы делаете.
Задумайтесь о целях вашей компании. Как то, что вы улучшите документацию, отразится на прибыли компании.
Для начала я провела аудит контента. Я перечислила все наши хранилища документации: что в них хранится, какая CMS используется, кто основная аудитория каждого из сайтов, кто пишет документы. Затем я рекомендовала, какие сайты следует оставить, с каких перенести информацию, а какие — полностью снести.
Приоритет номер один для технического писателя — это аудитория. Все, что мы делаем — мы делаем ради других людей, не для себя. Если вам повезло иметь продуктовую или маркетинговую команду, которые сегментируют аудиторию для вас, держитесь за неё, у меня не было такой команды.
Я сама поделила аудиторию на четыре группы по целям:
- Во-первых, это владельцы бизнеса, люди, которые интересуются приобретением продукта, хотят понять, что он умеет, общие принципы работы, как начать работать с ним.
- Вторая категория — это исследователи, они уже знакомы с продуктом, но хотят узнать о продвинутых функциях.
- Третья, это люди, которые хотят решить проблему, они пришли в документацию в панике, у них есть проблема, и они хотят быстро ее решить.
- Наконец, четвертая категория — это детективы, это могут быть менеджеры по продукту или инженеры, которым интересно, может ли ваш продукт выполнять какую-то специфичную функцию.
Разделив аудиторию на эти группы, я стала лучше понимать их цели, чтобы создавать контент, удовлетворяющий ожиданиям.
Нашей приоритетной проблемой было многообразие веб-сайтов, поэтому цель номер один — это консолидация контента, нужно было его реорганизовать. А это значит, сначала понять, что «хорошо», а что «плохо», что стоит сохранить, а что — нет.
Вторая цель — настроить связные шаблоны для разных видов контента, например, пошаговые инструкции, FAQ, обзор, чтобы читатель четко понимал, что за вид документа он читает. Это помогло нам сделать контент более находимым.
Кроме того, нам нужны были и внутренние цели, например, улучшить процесс того, как мы пишем понятные и информативные документы от запроса до публикации. Мы написали гайдлайн для составления запроса на документ, в нем мы прописали обязательные вопросы, на которые нужно ответить, например, зачем этот документ или какую информацию нужно обязательно в него включить. Таким образом, мне удалось избежать ситуации, когда я задаю вопросы вроде: «Что еще за новая функция? Что значит вам срочно нужна на нее документация, расскажите поподробнее».
Наконец, план документации был бы не полным без плана по выведению документов из эксплуатации: Что делать, если документ устарел или описывает продукт или функцию, которая больше не существует? Как мы планируем архивировать такие материалы? Может стоит удалять их совсем?
Вот что такое «план жизненного цикла документа», вы должны продумать каждый шаг от создания и до удаления документа. Для Joyent это означало, что с момента появления идеи, до написания текста, затем от его публикации до обновления, архивирования или удаления. Каждый шаг запротоколирован, есть проверки, что контент не теряется навсегда, что настроены предупреждения и редирект со старого документа на новый. Если пользователь будет искать старый документ, он не должен увидеть 404.
В результате у нас получился очень длинный список задач. Нам пришлось заново описать, что входит в скоуп продукта, какая должна быть архитектура сайта, какие виды контента, как сайт должен выглядеть вплоть до дизайна.
Вот еще несколько пунктов, которые я не буду раскрывать подробно: это расписание, дорожная карта, инструменты, которые нужны для реализации, оценка времени и затрат на переделывание документов и на покупку инструментов, а также ряд дополнительных вопросов, например, хотим ли мы open source документацию? Если да, как мы планируем это реализовать?
Независимо от того, какой у вас в итоге получится проект — длинный и детальный или маленький и компактный, например, «Александра и Филипп хотят собаку, потому что...», важно, чтобы ваш проект отражал четкие и понятные причины, почему вы планируете сделать так, а не иначе, как вы планируете решить проблему и сколько времени это займет.
Воплощаем проект в жизнь
Итак, ваш проект готов, вы впечатлили руководителя, он выделил ресурсы и время, а что дальше? Планирование — это прекрасно, проект помогает вам определить те продукты, которые требуют внимания. Вы можете переиспользовать часть проекта, многие из моих проектов становились шаблонами для будущей работы.
Настал момент собрать все части воедино. Следующий шаг после создания и утверждения проекта — это контент стратегия. На самом деле, большую часть работы вы уже проделали.
Шесть лет назад я работала менеджером по цифровому маркетингу в некоммерческой организации. Безусловно, маркетинговый и технический контент различаются, цель маркетинга — продавать, а технического контента — помочь, научить или посодействовать в выполнении задачи. Однако, мы можем пользоваться техниками из маркетинга. Контент стратегия позволяет добиться консистентности в брендинге. Когда пользователь использует продукты, читает рекламные материалы, читает документацию, то он должен чувствовать единство бренда.
К примеру, так выглядел сайдбар на сайте docs.joyent.com раньше. Признаться, сервисы несколько раз переименовывали еще до моего появления в компании, но было важно убедииться, что наш публичный продукт, Triton Compute Service, обновляется единообразно.
Слева вы видите пункты меню продукта Joyent Cloud. Это «наследие» предыдущего нейминга продукта — Joyent Public Cloud. Я обновила их, назвав раздел Triton images, теперь он соответствует названию продукта.
У нас все еще есть проблема с названием компании. Мы постоянно спорим с начальником, но чаще я проигрываю. Пользователи называют продукт JPC, кроме того, этот акроним используется в коде. Сложно оставить это название в прошлом. Но со своей стороны, мы можем хоят бы придерживаться названия продукта в материалах.
Говоря о нейминге продуктов, важно четко описать правила, как мы именуем продукты и компоненты, создать обновляемый глоссарий, чтобы добиться консистентности.
Он может быть частью стайлгайда, чтобы стандартизивать то, как мы рассказываем о себе, как говорим о других брендах, например, Docker. Стайлгайд может помочь договориться о том, какой тон, какие грамматические конструкции, стили текста и правила мы используем. В результате, вы и сами будете писать лучше, и получите от коллег черновики более высокого качества.
Еще одна важная часть стратегии — это собственно «снести» устаревшие документы и материалы. Я написала сообщения различным командам, что их контент не обновлялся более двух лет и будет удален.
Но, на самом деле, я не удалила его полностью, просто убрала из публичного доступа и отправила в архив, пока не убедилась, что там не осталось ничего ценного.
Интересный факт: Joyent — дочерняя компания Samsung, что значит, наши основные лица принимающие решения находятся в Корее.
Спустя два года работы над документацией в Joyent, меня попросили заняться полностью новым проектом. Это означало, заморозить ту контент стратегию, которую я бережно выстраивала, основываясь на знаниях о продукте. Вскоре я прекратила работать над пулл реквестами, которые получала на новую, ориентированную на задачи пользователя, версию сайта с документацией.
К этому моменту, почти все сайты, которые мы посчитали устаревшими, все еще оставались онлайн. Но я извлекла уроки из своей работы и начала в новом проекте с нуля.
Вывод такой: иногда приходится выбросить в трубу всю работу из-за сложившихся обстоятельств.
Не стоит чувствовать личную связь с тем, что вы делаете, иначе вам будет сложно отказаться от всего, что вы сделали. Ничего не должно быть для вас настолько ценным. Запоминайте выученные уроки и используйте в будущих проектах.
Что мы упустили
Несмотря на то, что пришлось оставить все позади, я все же извлекла несколько уроков из моей работы. А именно то, что я упустила.
Первый уроок, это пользовательское тестирование. На самом деле это следовало сделать приоритетом номер один, вместе с бюджетом на инструменты и время, которое нужно потратить на беседы с пользователями о том, что им нравится в документации, а что нет.
Более того, мне бы хотелось более пристально пообщаться с коллегами о том же самом. В конце концов, они тоже пользователи документации, их голос важен. Если включить их в процесс, у них будет больше мотивации помогать с документацией.
Я знаю, что пользовательское тестирование очень важно, даже в формате обычного опроса можно выяснить ощущения людей, что они хотели бы видеть. Мне следовало продавить эту задачу.
Не менее важна идея об эмпатии к инженерной команде. Как вы фасилитируете коллег, чтобы они писали более качественный контент, в то время как вы можете сосредоточиться на более общей стратегии и поддерживающем контенте?
Есть несколько способов, как встроить коллег в процесс создания документации, как продать им, почему это важно. Если мы хотим, чтобы они перестали гуглить ответы, создайте эти ответы внутри компании.
Также, помните, что даже у тех коллег, которые верят в важность документации, есть свои приоритеты. Они занятые люди. У них есть свои цели и задачи перед руководством. Им нужно сначала закончить свою работу, а потом помогать вам. Будьте добры, поддерживайте их.
Вероятно, самое сложное в этом процессе, это убедиться, что эксперты и инженеры понимают, что этот процесс важен. Еще лучше, если документация — это часть инженерной культуры вашей компании.
Документация — это задача каждого, не только писателей. Если все стремятся решить проблемы пользователя, продукт становится лучше.
Учитывать разнообразие — важный момент для Joyent, ведь у нас есть сотрудники в Южной Корее, нам нужно было понять, как они мыслят. Их способ поиска информации и решения проблем часто отличался от нашего.
Культура организации влияет на документацию. На самом деле, написание текстов всегда зависит от того, как именно мы учимся, и от того, как нам кажется должны учиться другие.
Разнообразие — это важно. Иметь в команде людей с разным бэкграундом позволяет лучше учитывать разные модели обучения и создавать более качественный контент. И здесь есть немало пространства для роста.
Напомню основные идеи этого рассказа. Во-первых, о том, как написать классный проект по переработке документации, во-вторых, как сделать первые шаги по реализации этого проекта, и, наконец, о том, что я изначально упустила в процессе работы, а вот вы не должны. Ключевые выводы такие:
- Планы — это ключ к успеху. Они включают проект и стратегию.
- Но иногда планы ничего не значат из-за вмешательства обстоятельств. Иногда результат сразу идет в продакшн, а иногда приходится оставить его и двигаться дальше, начать все заново после того, как сделал половину работы.
- Документация важна как для пользователей, так и для инженеров. У вас есть критические навыки, вы помогаете другим понимать сложные концепты и процессы. Ваша работа важна, как и вы сами. Даже если вам этого не говорят.
Будьте пастухом своего стада. Ведите пользователей и коллег к ответам, которые им нужны.
Полезные материалы к докладу:
Вы можете подписаться на Александру в Twitter, Github, читать ее личный блог или пообщаться с ней вживую 26 апреля на KnowledgeConf 2019 после ее доклада или на стенде международного сообщества технических писателей Write the docs.
Автор: Светлана Новикова
