Что делает писатель в компьютере
Мы — сплоченная команда технических писателей. Сейчас нас одиннадцать человек: десять писателей и один технический редактор-переводчик. Среди нас есть инженеры, программисты, филологи и педагоги. Мы все очень разные: по возрасту, характеру, увлечениям и образованию. Но нас объединяет одно общее интересное дело — документирование сложных систем и решений.
Погружение в процесс
Каждый писатель редактирует DITA-файлы у себя в локальной копии, а затем выгружает изменения в SVN. Часто бывает так, что над одним документом работает несколько писателей. Чтобы в этом случае не было конфликта правок, у нас есть специальный чат, где можно оповестить своих коллег о начале работы с определённой частью документа или об обновлении общих коллекций, например — глоссария. Может, это и не самое технологичное решение, но оно работает. Никому из писателей не хочется потом «мёржить» (merge) куски сложных технических текстов.
После обновления локальной копии SVN начинается работа. Мы работаем по задачам в Jira. У нас есть специальный тип задач с префиксом DOC. Обычно они связаны с задачами на разработку или с запросами заказчиков. Задачи на документирование создают менеджеры, которые ведут проект, тестировщики, сотрудники службы поддержки. Заказчик тоже может инициировать изменение документации, задав вопрос, высказав пожелание или жалобу. Team Lead нашей команды планирует деятельность каждого писателя, распределяет задачи, следит за их выполнением и отгрузкой документов.
Для всех участников процесса разработки главное — не забыть создать задачу, ведь писатели должны откуда-то узнать о том, что что-то нужно задокументировать. К сожалению, у нас всё ещё бывают такие ситуации, когда подходит срок отгрузки новой системы, а заявка на документирование этой системы не создана. В этом случае чуда не произойдёт — документация не появится моментально.
Последний штрих
Заканчивается рабочий день технического писателя тем же, чем и начинался — синхронизацией с SVN. Конечно, мы часто выполняем промежуточные синхронизации и в середине дня, но вечером обязательно проверяем, все ли изменения выгружены на сервер. Будет обидно, если вся работа, сделанная за день, пропадет даром. И конечно, надо не забыть оформить трудозатраты — вписать в задачи Jira время, которые мы на них потратили за этот день.
Диалоги
Используя наш редактор диалогов, мы создаем реплики для каждого разговаривающего персонажа в игре. Очень, очень много раз. Написание диалога — это итеративный процесс, и после очередного ревью очень много текста должно быть отредактировано, переписано или вырезано напрочь. В зависимости от того, как ощущается прохождение игры, у персонажей могут изменяться имена, пол, профессия, вообще всё. Иногда персонаж, которого ты по настоящему любишь, не проходит ревью живым, и тогда пригождается старый совет одного писателя “убивай всех любимчиков”. Так тяжело всаживать нож, когда у твоих любимчиков есть лица!
Внутри нашей команды, мы каждый день проводим небольшие ревью текстов друг друга, чтобы сделать их максимально идеальными. Иногда кто-нибудь из нас застревает на диалоге, просто не может подобрать нужные слова, — и это момент, когда быть частью команды здорово, мы можем просто поменяться диалогами и посмотреть на все свежим взглядом. Наша цель, чтобы каждый диалог звучал реалистично, фокусировался на игроке и улучшал какой-нибудь аспект нашего мира при этом не разрушая его целостность! Это приказ!
Нужен ли вашей игре писатель?
Если ваша игра использует хоть какое-то количество текста, то я бы сказала “Да!”.
Писательство как дисциплина часто страдает от идеи, что если каждый может печатать, то каждый может писать. Если вам нужен гладкий сюжет, цепляющие диалоги, интересные окончания квестов и развлекающий маркетинговый контент, инвестиции хотя бы в одного писателя помогут добиться значительного прогресса для вашего проекта.
Даже там где слов мало, именно писатель понимает и может соединить сюжетные линии, мотивации персонажей и найти правильные слова для меню, команд и т.д.
Если вы не в состоянии нанять писателя на постоянной основе, то даже небольшие консультации писателя -фрилансера могут сотворить чудо и для того, чтобы ваша игра смотрелась более отполированной и профессиональной, и для того, чтобы ваши сюжеты были более законченными и сверкали цепляющими фразами, которые будут возвращать игроков снова и снова.
Этот специалист «переводит» непонятный язык программистов, разбирается в специфических темах, изучает технические нюансы продукта, над которым работает команда, и детально все разъясняет пользователям. То есть он говорит просто о сложных вещах. Если вкратце, то такова суть работы технических писателей. Подробнее об их обязанностях, роли на проектах и старте карьеры в данной сфере в интервью с тренером курса по technical writing , опытным техническим писателем, бизнес-аналитиком в Exadel Натальей Степурко.
– Наталья, расскажите, что входит в круг обязанностей технического писателя в IT-компании?
– Если мы начнем с расшифровки значения «технический писатель», то сразу частично определим круг его обязанностей. Это специалист, отвечающий за создание и обновление технической документации. Я бы назвала технического писателя посредником между продуктом и конечным пользователем. Главная обязанность данного специалиста – объяснить сложный продукт простым понятным языком так, чтобы пользователь мог решить проблему или добиться своей цели. В отдельных случаях, технический писатель может работать в коллаборации с бизнес-аналитиком и создавать документацию для команды разработки. Но подчеркну, что такой вариант взаимодействия встречается не так часто.
Хотелось бы еще пояснить, что технический писатель не есть копирайтер. Это схожие позиции, но они имеют ряд существенных отличий. Технический писатель пишет техническую документацию с нуля, а не переписывает маркетинговые тексты для блогов с целью, например, продвижения сайта.
– Какое место занимают технические писатели на проекте? Всегда ли есть необходимость «в подключении» данных специалистов?
– Технический писатель появляется на проекте, в котором продукт характеризуется сложной логикой. Например, всем известное приложение для знакомств Tinder не нуждается в документации по некоторым причинам: оно user-friendly, имеет ряд подсказок на экране, очень понятно в использовании. В то же самое время, такой продукт как Google docs имеет документацию, так как есть ряд настроек, которые не лежат на поверхности и пользователю-новичку сложно понять, как всё работает.
Технический писатель – полноправный участник команды разработки. Если в компании есть команда технических писателей, то уже с самого начала проекта специалист будет работать над продуктом. Его деятельность будет заключаться в анализе конечного пользователя и его задач. Как следствие, технический писатель должен спланировать, какие типы и виды документов нужны для продукта. Дополнительно он может помогать команде разработки правильно называть кнопки на интерфейсе, формулировать подсказки при наведении. Чаще всего для выполнения своих обязанностей техписатель взаимодействует с тестировщиками, бизнес-аналитиками и, возможно, с владельцем продукта.
– Подготовкой технической документации в IT занимаются не только технические писатели. В чем заключаются ключевые отличия их работы, скажем, от обязанностей бизнес-аналитика?
– Бизнес-аналитик составляет документацию для команды разработки, которая на основе документов делает продукт. Технический писатель создает документацию для конечного пользователя – того человека, который продуктом будет пользоваться. Грубо говоря, описывает уже готовый продукт. При этом бизнес-аналитик может повлиять на логику продукта, а технический писатель нет.
– Какие требования предъявляются к техническому писателю на старте карьеры? Что он должен знать и какими инструментами владеть?
– Основа для работы техническим писателем – это навыки письма. Умение писать на английском, чувствовать язык, при этом знать правила и алгоритмы написания именно технической документации.
Что касается инструментов, то на старте было бы желательно знать и уметь пользоваться такими продуктами как MadCap Flare and Robohelp, но на самом деле не обязательно, потому что многие компании не могу позволить себе купить лицензию, которая стоит тысячу долларов. Потому в таких компаниях все довольно просто в плане инструментов: нужно знать Google Docs, Confluence, Jira.
– Чего ждать потенциальным слушателям от курса по техническому писательству?
– В основе курса лежит современный подход к написанию документации. Выучив его один раз, можно будет создавать такие документы как User Guide, Installation Guide, Manuals, Training Manuals, Online Help.
Каждое занятие (кроме вводного) состоит из теоретической части – лекции, и практической – workshop. Чтобы отточить навыки, слушатели будут получать домашние задания. Во время курса мы учимся писать именно на английском языке, поэтому на старте требуется знать его минимум на уровне Intermediate. Итого будет 15 воркшопов, 15 домашних заданий и финальный командный проект, на подготовку которого отводится две недели. Уверена, что такая формула способствует прокачке навыков лучше всего. Поэтому если есть интерес к профессии технического писателя, смело записывайтесь на курс «Technical writing» .
– Будет ли прохождения программы обучения в IT-Academy достаточно для получения работы в IT?
– Мой ответ да, достаточно. Поясню почему: если слушатель уже знает английский язык на продвинутом уровне, к чему прибавляются теоретические и практические знания для написания техдокументации, плюс он является любознательным и коммуникабельным, умеет работать как в команде, так и в одиночку, то есть все шансы трудоустроиться по новой специальности.
Более того, в ходе обучения студенты выполняют домашнюю работу и финальный проект, которые пригодятся для портфолио. Еще раз акцентирую внимание: все задания на курсе на английском, что тоже можно назвать отличной практикой, ведь в IT-компаниях в большинстве случаев нужно будет работать именно с этим языком. Прежде чем пригласить на собеседование, зачастую изучается портфолио кандидата. И оно у вас после курса будет. Если работодателю нравится портфолио, то успешность трудоустройства зависит от умения показать себя на интервью. Сомневаетесь в способностях самопрезентации? Тогда после курса по technical writing можно пройти бесплатные тренинги по soft skills , которые доступны выпускникам IT-Academy 2020 года. Такая подготовка в совокупности повышает шансы на получение работы в IT.
Долгие столетия писательский труд был именно писанием, то есть собственноручным испещрением клочка бумаги (папируса, пергамента) затейливыми черточками, петельками и крючочками.
Но вот наступил ХХ век с его постоянно совершенствуемыми возможностями машинописи, а привычка к рукописанию никуда не делась. Писатели упорно продолжали покрывать своими каракулями тонны бумаги.
Почему? Послушаем их самих:
Пишу карандашом. Мне нужно не менее дюжины их и машинку для заточки. О, и очень много бумаги! Пишущая машинка — для окончательного варианта и для копий.
Когда пишу от руки, у меня создается впечатление, что я более искренен, не столь литературен. За пишущей машинкой у меня все получается слишком гладко. Это напоминает проигрывание фортепьянных гамм. Моими мыслями каким-то образом управляют пальцы.
Я пишу от руки, потому что не привык думать за машинкой. Мне нужно чувствовать в руке карандаш, видеть, как из-под кончика карандаша выходят слова, и, если слово не то, я его просто стираю и пишу новое. Мне надо все сначала записать на бумагу. Только после этого я перепечатываю все на машинке, но сначала мне нужно, чтоб текст был написан от руки, чтоб я чувствовал его.
Перо. Пишущая машинка, мне кажется, должна вредно влиять на ритм фразы.
Нарезаны четвертушки бумаги, очинен химический карандаш, приготовлены папиросы, я сажусь за стол.
Пишу пером. Карандашом пользуюсь иногда для отделки какой-нибудь фразы. Рисунков на рукописи не делаю. Возможности печатать вещи сразу на пишущей машинке искренно не понимаю.
Я пишу только ручкой, только на хорошей бумаге. Бумагу я привезла из Швейцарии. Я люблю хорошие ручки, чтобы была легкая подача чернил. Бумага и ручка мне не должны мешать.
Во время работы я не выношу шума машинки. Я наедине с мягким «самопишущим» пером и квадратной глянцевой бумагой.
Щелканье машинки мне мешает, я всегда пишу только пером. Перо для меня не безразлично — писать люблю мягким пером, если есть, то медным.
Если бы я показал вам свою записную книжку, вы бы обнаружили массу завитушек, и стрелочек, и легких зачеркиваний, сквозь которые проступает первый вариант. Переходишь от этого к печатному тексту — и он тут же выглядит более закоснелым. Кстати, все это чепуха насчет того, что на компьютерах удобнее жонглировать текстом. Ничто не сравнится с возможностями рукописи. В ней ты переставляешь куски текста, физически не сдвигая их, то есть всего лишь указываешь на возможность перемещения, оставляя изначальную мысль нетронутой. Проблема компьютера в том, что у конечного результата нет памяти, нет происхождения, нет истории — маленький курсор (или как он там называется) дрожит где-то в центре экрана, создавая иллюзию того, будто вы думаете. Даже когда вы давно уже перестали.
Когда я учился писательскому мастерству в колледже, мне приходилось, как и всем, сдавать свои сочинения, набранными через двойной интервал шрифтом Times New Roman. И у меня все выходило ужасно. Стоило мне только начать писать от руки, как работа пошла веселее, и ее качество заметно улучшилось.
Чем дальше я держусь от компьютера, тем лучше становятся мои идеи. Microsoft Word — это мой враг. Я все время пользуюсь им на работе, поэтому в остальное время стараюсь с ним не связываться.
Думаю, что чем больше писательство становится физическим процессом, тем лучше получаются произведения. Можно почувствовать чернила на бумаге. Можно разложить листы по всему столу и перебирать их. Можно положить текст везде, где на его будет удобно смотреть.
Тем не менее, технический прогресс постепенно находил все больше сторонников среди пишущей братии. Уже в начале 1920-х годов печатная машинка стала неотъемлемой принадлежностью писательских столов.
Я работаю сразу на машинке, правлю по окончании каждой страницы, очень много вычеркиваю, без жалости, если даже какое-то отдельное сравнение кажется удачным, переписываю и снова мараю. В итоге каждая страница — это восемь-девять склеенных кусочков. Другой метод — написать все произведение вчерне, а затем переписывать начисто — куда экономней, но у меня отвращение к плохо написанному тексту. Такой же отделке подвергаю каждую законченную главу. Это опять-таки не экономно. Но когда пишешь главу, хочется, чтобы все в ней было ясно; тогда чувствуешь, как постепенно меняется форма всего произведения.
Я пишу на машинке с 1930 года — испортился почерк. Работаю я медленно. В лучшие годы писал не более пяти отделанных машинописных страниц в день при работе с утра до ночи. Вечером я только правлю написанное.
На пишущей машинке. Рукописный текст всегда неясен (не разборчивость почерка, индивидуальность его, малое — сравнительно с печатным — количество слов на странице). Все это мешает каждую минуту отрешаться от себя, взглядывать критически, как на чужое, на свою работу. Когда фраза слишком сложная, или когда они толпятся, забегая вперед, — набрасываю их пером. Мне никогда не удавалось набросать от руки больше трех, четырех страниц, сейчас же тянет взглянуть на это в печатном виде — на машинке.
Техника письма. Набрасываю пером и сейчас же стукаю на машинке. К карандашам чувствую отвращение.
Рассказы до листа пишу на машинке сразу, больше листа — пером и затем на машинке.
В конце ХХ века нашлись свои поклонники и у компьютера.
Писал от руки. Печатал черновик на машинке, правил, перепечатывал. В середине 1980-х с радостью перешел на компьютер, и теперь пишущая машинка кажется мне грубой механической помехой. В текстовом редакторе есть что-то более интимное, он ближе к мысли как таковой. Эфемерность еще не распечатанного материала похожа на невысказанную мысль. Мне нравится возможность без конца переделывать фразы, мне нравится, как преданная машина запоминает все мои маленькие пометки.
Особняком в этом отношении стоял Л.Фейхтвангер, который имел обыкновение надиктовывать свои романы.
Наконец, сформировалась еще одна группа писателей, которые сочетают возможности пера и печатной машинки (компьютера).
Сначала я все пишу от руки. Писать от руки я могу в течение двух часов, не больше, — пальцы немеют. Тогда я откладываю ручку и начинаю перепечатывать написанное, попутно что-то меняя; пожалуй, это первая стадия редактирования.
Первые сто страниц пишу не оглядываясь. Пишу от руки. После того как этот первый вариант жена напечатает или наберет на компьютере, я обычно весь его перекраиваю, правлю, выбрасываю нещадно абзац за абзацем. Если у меня от десяти рукописных страниц остается одна печатная — это хорошо.
Я пишу не только на компьютере, иногда и от руки тоже. Рукой я написал «Ловца снов» и «Мешок с костями» — хотел понять, как получится. Кое-что изменилось. Прежде всего, дело пошло медленнее — когда пишешь от руки, времени уходит больше. И каждый раз, когда я начинал писать, во мне просыпался лентяй и говорил: «А это обязательно?» У меня после этих упражнений до сих пор мозоль на пальце. Зато работа с черновиками была куда увлекательней. Мне показалось, что первый вариант получился более отточенным — все потому, что спешить не получалось. Ведь писать можно только с определенной скоростью. Это все равно как мчаться на мотоцикле или идти пешком.
Я раньше тоже сочетал рукописание и стучание по машинке и клаве, но последние годы мараю страницы только на мониторе. Мне тоже необходимо видеть сразу всю фразу, а часто — и весь абзац для того, чтобы добиться необходимого ритма, избежать повторов, увидеть слабые места и т.д. Кроме того, историк поневоле использует много цитат, а их удобнее копировать и переносить в текст при помощи мышки :).
Призвание
Работа технического писателя — сложная, но действительно интересная. Каждый день мы придумываем, как упростить и сделать понятными сложные алгоритмы, правила и системы, как сделать документацию удобной, полезной и красивой. В компании разрабатываются новые системы, постоянно добавляется функциональность в уже существующие системы. А это значит, что наша работа никогда не станет скучной и однообразной. Вносить ясность, добывать смысл, помогать читателю-пользователю решить любую задачу — в этом и есть наше профессиональное призвание.
Привет! Я Катя, руководитель группы технических писателей в Ozon. Сейчас нас уже 9 человек и целая платформа документации, но коллеги всё ещё не всегда понимают, чем мы занимаемся.
Из непонимания появляются запросы вида: “Хотим себе собственного техписателя в команду, но не знаем, чем именно он будет заниматься”. В итоге команда подстраивается под тренды и заводит себе документацию, но через пару месяцев оказывается, что доку не читают, а техписатель плавно превратился в аналитика.
Поэтому пришло время делиться опытом и рассказывать о каких-то концептуальных штуках :)
Инструменты писателя
Мы пишем документацию в формате DITA. Это формат, основанный на XML, который позволяет сохранять исходный текст документов в структурированном виде. Мы пишем исходники документации в этом формате, для этого у нас есть редактор oXygen XML Author. Затем из этих исходников мы можем собрать итоговый документ в любом нужном формате. Для этого есть специальный Toolkit, содержащий XSLT-преобразования. Наш Toolkit позволяет собирать документы во множестве форматов. Самый востребованный — это PDF, иногда собираем CHM или HTML. При желании мы можем собрать даже EPUB, если заказчик вдруг захочет почитать нашу документацию перед сном на электронной книге. По необходимости мы вносим правки в XSLT-преобразования, чтобы изменить правила сборки документов и их внешний вид.
Как понять, что пора заводить технического писателя?
Если у вас есть продукт, которым пользуется кто-то снаружи — час пробил. Даже если "снаружи" сидит в соседней команде. Любое погружение посторонних в ваш продукт или проект уже подразумевает документацию, а, следовательно, и позицию технического писателя.
Но есть нюансы:
Документации нет и это не создаёт никаких реальных проблем — техписатель не нужен.
Документацию уже кто-то пишет и ему проще делать это самостоятельно, чем объяснять техписателю — у вас уже есть технический писатель, только называется он "инициативный разработчик" или "ответственный аналитик".
В системе часто что-то меняется — чаще, чем приходится систему кому-то объяснять — проще рассказать на словах, чем поддерживать все изменения. Часто можно сказать: "Ребята, сейчас используем вот эту штуку, документация на официальном сайте", а не расписывать подробные инструкции, которые через пару месяцев уже будут не нужны.
Подумайте о документации как о продукте — оцените её потенциальную аудиторию и задачи, которые она должна решать. Возможно, вам нужна не документация а вебинар, скринкаст. Или даже стикерпак.
Кто вообще такие технические писатели?
Встречала разные ответы, от "ребята, которые пишут никому не нужные талмуды по ГОСТам" до вполне близких к моей реальности определений.
В Ozon технические писатели занимаются глобально тремя направлениями:
пользовательской документацией (Помощь, База знаний, FAQ),
документацией внешних API,
описанием внутренних систем — от онбордингов до сложных архитектурных взаимодействий.
Какое в итоге "правильное" занятие для техписа — поле для холивара — в Ozon вот так, в других компаниях может быть иначе. Когда я работала в Яндексе, например, конкретно моя команда не сильно занималась внутренними документами.
Ещё к нам часто приходят просто за качественными текстами — для лендингов, постов, обучающих курсов. Нам интересно, и мы не отказываем, но не могу сказать, что это попадает под именно техническое писательство.
При желании мы можем писать в принципе любые тексты, но будьте готовы, что от техписателя текст получится с уклоном в техническую часть, без завлекающих и рекламных заголовков.
Технические писатели описывают, как устроены какие-то системы и как с этими системами работать. Это может быть пользовательская инструкция по оформлению возврата или схема взаимодействия методов API — но это всегда ответ на вопрос "как что-то сделать".
Главная история
Мы работаем над написанием и балансировкой главного нарратива, принимая во внимание комментарии от всех команд. Команды художников, дизайнеров и маркетологов — все работают с тем, что мы пишем, и надо быть уверенным, что наши тексты настолько описательны и подробны, насколько это возможно, и что любые серьезные изменения могут быть поняты без труда. Любой сюжет разрабатывается от общего к конкретному, т.е. органично с главного настроения, постепенно разрастаясь и формируясь через длинную череду встреч у доски, криков друг на друга, моря кофе и смеха.
Конечно, как и все писатели, мы считаем, что история — это главное. Но к концу дня понимаешь, что главным все-таки является игровой процесс (геймплей). Не важно, насколько красива наша проза, — если она не сочетается с игрой, все будет разорвано в клочья и выброшено в корзину. Так что требуется несколько итераций, чтобы создать по настоящему хороший сюжет, который будет при этом хорошей игрой.
Кто мы?
Итак, кто же становится писателем/сценаристом в игровой студии? В Larian мы, писатели, — небольшая, но разношерстная команда. У всех нас очень разные профессии в прошлом, включая историка, сценариста для фильмов и тех. менеджера. Объединены мы лишь тремя вещами: страстью к печатному слову, любовью к RPG и тотальным желанием доминировать в словесных играх.
Мы очень много читаем. Мы делимся книгами, комиксами и рекомендациями фильмов со всеми четырьмя офисами по всему миру, что помогает сформировать уникальную мета культуру. Последний год наши интересы лежат в области фэнтези, научной фантастики и русской литературы. Это повлияло на формирование очень черного чувства юмора у всей команды.
Описание мира
Кстати о целостности… а как гномы общаются друг с другом? Каковы ритуальные правила эльфийского каннибализма? Какая конкретно иеарахия в Святом Ордене? Примерно такие вопросы мы получаем от команды дизайнеров каждое утро понедельника. Картина большей части нашего мира уже существует в нашем воображении и в наших документах, но всегда есть эти небольшие мазки, которые нужно добавить, — и мы именно те, у кого в руках кисточки.
Подробнее о формате
Формат DITA вообще оказался очень удобным инструментом именно для разработки технической документации с её специфическим содержанием. Например, мы можем повторно использовать любой блок текста или целый раздел из одного документа в другом документе. И это будет не привычный «copy-paste», а именно использование одного блока в разных документах. Если в этом блоке что-то изменится, нам достаточно будет поменять текст один раз — изменение автоматически попадёт во все документы. Ещё мы можем применять фильтрацию — написать один универсальный раздел, вставить в несколько документов и потом фильтровать его содержимое в зависимости от типа документа, заказчика, системы и других параметров. А ещё мы не задумываемся о перекрёстных ссылках между разделами — достаточно в нужном месте указать ключ раздела, на который мы хотим сослаться. Toolkit при сборке документа сам пронумерует разделы и сделает красивые гиперссылки.
Где искать технических писателей и как оценивать кандидатов?
Я пришла в техписательство после бакалавриата компьютерных наук в Иннополисе, года автоматизированного тестирования и академии от Яндекса.
Кто-то приходит из лингвистов и филологов со стремлениями уйти в аналитику или разработку. Я стараюсь искать (особенно стажеров) по техническим вузам; там довольно много ребят, осознавших, что кодить 24/7 — не их стезя. А вот что-то рядом, но чуть гуманитарнее — наш идеальный кандидат.
Если нужен сильный специалист, который всё вам сделает под ключ — профильные сообщества, митапы. Если хватит и молодого, зеленого, но перспективного — чаще всего это кандидат совсем без опыта, но с сильным тестовым и пониманием мира IT.
Если это ваш первый технический писатель на проекте, дайте что-то про описание процесса или архитектуры. Оцените полноту описания, структуру и термины, которые использует кандидат. Прочитайте Ильяхова или подпишитесь на рассылку о текстах, чтобы примерно понимать, где хорошо, а где не очень. Но важнее, чтобы устраивало конкретно вас и попадало в формат компании, чем полное соблюдение концептов информационного стиля и 10 баллов по Главреду.
Большие надежды — портал bercut.web.docs
Конечно, PDF-файлы — это не самый удобный формат пользовательской документации. К примеру, поиск нужной информации можно выполнять только в рамках одного PDF-файла. Нельзя поискать описание какого-то параметра сразу во всей документации по системе. Это очень неудобно, ведь количество документов на одну систему часто исчисляется десятками. Если не знать, в каком документе искать нужные данные, то поиск превращается в нетривиальную задачу. Сейчас мы работаем над созданием портала, на который сможем выгрузить документацию в формате HTML. Там будет предусмотрен удобный полнотекстовой поиск по всем страницам или по части документации, например, по страницам на определенную версию определенной системы.
Как выстроить процесс?
Чаще всего у документации есть заказчик. Это может быть менеджер, разработчик, дизайнер — любой человек, осознавший, что есть какая-то проблема в понимании происходящего. Задача техписателя — определить, реальна ли проблема и в каком формате её нужно решать.
В общем виде документация создаётся по такому сценарию:
Определить цель документа и его аудиторию.
Набросать структуру, согласовать с заказчиком. Скорее всего, изменения будут, здесь важнее понять какие вопросы хочет покрыть заказчик.
Понять, кому и по каким темам можно задавать уточняющие вопросы — найти экспертов и договориться о формате работы с ними.
Наполнять документ и параллельно отдавать на вычитку коллегам-техписателям и экспертам.
Финализировать структуру и тексты — обязательно отдать кому-то на вычитку и после этого презентовать заказчику.
Этапы не должны затягиваться. Если пошёл уже пятый круг обсуждения структуры документа, который ещё даже не начали наполнять — что-то пошло не по плану. Финальное согласование с окончательной заморозкой структуры и текста происходит только тогда, когда уже всё написано и проверено.
Часто слышу, что технический писатель, особенно если он один на проекте, просто сидит и что-то пишет целыми сутками, без вычиток и конкретных задач. "Ну он же технический писатель, пусть и пишет всё сам" — бесспорно, существуют люди, которым комфортно работать в таком режиме, но в очень редких случаях это ведёт к хорошей документации и довольному сотруднику.
Моя формула найма: 1.5 техписателя на проект. За половинку может считаться стажер или техписатель из другой команды — так есть и с кем экспертизой обменяться, и кто на время отпуска-болезни подхватит проекты.
Нужен ли вам техписатель: чеклист
Чтобы понять, действительно ли вам нужен технический писатель, задайтесь вопросами:
Кому может понадобиться документация к моему проекту? Моим же разработчикам, внешним пользователям?
Как проблема отсутствия документации решается сейчас? Система понятна и без дополнительного описания? Может, кто-то уже снял обзор по этой теме на YouTube?
Если документация всё же нужна, в каком виде её будет удобно потреблять? Всплывающие подсказки, вебинары, отдельный URL с базой знаний?
Чем будет заниматься технический писатель, когда напишет документацию? Продолжит её актуализировать? Перейдёт на соседний проект?
Начинайте поиски технического писателя, только если у вас сложилась общая картинка о месте документации в вашем проекте. Отнеситесь к документации как к полноценному продукту.
Прочее
Когда мы не работаем над перечисленным выше, мы занимаемся журналами, тул-типами, боевыми кличами, пишем тексты для маркетинга и т.д.
Несмотря на то, что мы все занимаемся разными областями в игре, у каждого из нас есть своя зона ответственности. Например моя — это названия и описания каждого предмета в игре. Один из моих коллег отвечает за стили и их грамматические соответствия.
В дополнение, каждый из персонажей игрока закреплен за писателем, чтобы тот поддерживал постоянство стиля в его репликах (я немного влюблена в своего: Ifan ben-Mezd). Распределяя области ответственности таким образом, мы всегда уверены, что есть пара глаз, являющаяся финальным контролем качества для каждого слова, которое появится в игре.
Также стоит отметить, что очень вероятно, что в игре нет ни единого слова, которое кто-то из нас может признать своим достижением. Это командное достижение. Все, что проходит через многочисленные итерации и проверки, в результате оказывается продуктом, состоящем из частичек души каждого из нас.
В студии
Большая часть команды писателей (пять из семи) находится в нашей студии в Дублине. Тем не менее, студии не разобщены. Весь день мы поддерживаем контакт с коллегами через Slack и Skype. Этого общения так много, что я, скорее, больше общаюсь с моими коллегами-скриптерами из Санкт-Петербурга, Гента и Квебека, чем с коллегой-писателем, который сидит рядом в Дублинском офисе!
Почему так происходит? Как уже упомянуто выше, каждая ситуация в игре назначена писателю и скриптеру для совместной работы. Писатели в Дублине и Генте, скриптеры во всех четырех офисах — мы постоянно перемешиваемся для создания разнообразных игровых ситуаций.
И нас нужно смешивать. Сейчас, когда мы уже постигли “Путь Larian”, нас — писателей — нельзя оставлять одними надолго, иначе мы свихнемся. Если ты писатель, который привык сидеть в тёмной комнате в компании одной лишь музы, то тогда скорее всего в Larian тебе будет тяжко. Мы больше похожи на Борг или колонию муравьев (почему все эти сравнения звучат так негативно?!) работающих в общих документах, где всё раскрыто, комментируется, разрабатывается и постоянно редактируется. И при наличии настолько распределенной команды хорошая документация является ключевым фактором для того, чтобы быть уверенными, что все работают на одной волне.
В конце концов, после всей этой суеты, а что же происходит, когда мы наконец довольны нашим персонажем или сюжетной историей, или фразой, или диалогом? В этот момент вся остальная студия делится своими безжалостно честными отзывами. И это хорошо, потому что следующий этап — это наши игроки. Мы хотим, чтобы они полюбили и оценили нашу работу. Критика бывает тяжелой. Когда ты проводишь ночи на пролёт, оживляя и создавая персонажей и диалоги, трудно не воспринимать критику лично. Но это необходимо. Все что мы делаем, мы делаем ради игры, создавая максимально лучший опыт для игроков. И наш метод производства этого лучшего опыта состоит из постоянного партнерства, критики и новый итераций. И это работает!
Праздник труда
Работа технического писателя не такая однообразная, как может показаться со стороны. Мы пишем очень разные документы — у нас есть и справочники с большими таблицами параметров или полей БД. Есть руководства пользователя с подробным описанием каждой кнопки интерфейса. Есть руководства администратора со множеством технических подробностей о работе и установке системы. Но самый сложный, и при этом самый интересный, тип документа — это руководство по настройке. В нём комплексно описывается реализация определённого решения в разных системах и подробно объясняется что и где нужно настроить, чтобы это решение заработало. Писателю приходится писать разные типы документов — сегодня часами описывать один за другим параметры системы, а завтра думать над тем, как понятнее и проще описать алгоритм работы решения в руководстве по настройке. Но в любом случае писатель должен быть внимательным, аккуратным и педантичным.
Процессы и коммуникации в новой дистанционной реальности
Как и большинство наших коллег в IT-сфере, сейчас мы работаем из дома. Переход на удалённый режим работы, конечно, внёс некоторые коррективы в нашу повседневную деятельность, но рабочие процессы от этого почти не поменялись. Мы всё так же пишем пользовательскую документацию, всё так же общаемся с коллегами в Teams и Skype, пользуемся теми же рабочими инструментами и серверами. Разве что звонки по местным телефонам мы заменили перепиской и созвонами в мессенджерах.
Внутренняя «кухня» — источники вдохновения
Начиная работать над очередной задачей, писатель изучает многочисленные источники информации и преобразует полученные оттуда данные в пользовательскую документацию. Источников у нас много. Самый главный — это технический проект (ТП), которые пишут бизнес-аналитики ещё до начала разработки. ТП — это закон для разработчиков, тестировщиков и технических писателей. В идеале всё должно быть реализовано именно так, как написано в ТП. На деле же оказывается, что итоговая реализация отличается от ТП. Вы знаете, как это бывает: что-то не учли, что-то поняли неправильно, что-то оптимизировали… Для того, чтобы узнать, как на самом деле всё было реализовано, мы используем техническое описание (ТО), которое пишут разработчики. Там есть больше технических подробностей, описаны изменения конкретных типов данных и таблиц в БД, приведены алгоритмы работы процедур серверного кода, приведены скриншоты добавленных или изменённых окон в клиентских приложениях. Без ТО нам было бы очень трудно написать полноценную документацию. К сожалению, разработчики иногда откладывают написание ТО на самый последний момент.
Есть ещё один важный источник — описание настроек интеграционного тестирования. Там подробно описаны все настройки, которые нужно сделать в системах, чтобы пройти все тестовые сценарии (тест-кейсы). Этот источник незаменим для написания руководств по настройке.
ТП, ТО и описание настроек — это основные источники, из которых писатель получает информацию. Но есть ещё множество дополнительных: исходный код серверных процедур и клиентских приложений, XML-описания параметров, страницы в базе знаний Wiki, наконец — вопросы разработчикам и тестировщикам в мессенджерах. Ну и, конечно, сами системы — их web-интерфейс, клиентские и серверные приложения.
Задача писателя — объединить всю полученную информацию и написать простую, понятную и хорошо структурированную документацию о системе или решении. Тут нужно быть очень внимательным — ничего не перепутать, не забыть, описать именно то, что было реализовано. Писатель должен самостоятельно разобраться во всех особенностях реализации, понять все алгоритмы и принципы работы системы от начала и до конца. Только так получится хорошая и качественная документация.
Да здравствует Команда!
Также по пятницам у нас обычно проходит еженедельное совещание нашей команды в Skype. Эта традиция появилась у нас с переходом на удалённый режим работы. На совещании наш Team Lead делится с нами свежими новостями компании Bercut, рассказывает о новых краткосрочных и долгосрочных задачах и планах. Писатели по очереди рассказывают о своих задачах и рабочих проблемах — что сделано за прошедшую неделю, что планируется сделать на следующей. Такое обсуждение помогает нам скоординировать свои действия, ведь часто над пакетом документов к очередной версии системы работает сразу несколько писателей.
Биоритмы и конвенции
Режим рабочего дня, как и процессы, тоже не особо изменился. Ещё до перехода на удалённый режим в нашей компании каждый сотрудник мог выбирать время начала рабочего дня: кто-то приходил на работу в 8 утра, кто-то — в 11. Главное, чтобы все были на месте в определённый дневной период и работали положенные 8 часов. На удалёнке эти правила сохранились. Среди нас есть свои «совы» и «жаворонки» и каждый начинает рабочий день в удобное ему время. В любом случае проснуться можно попозже — ведь не нужно тратить время на утренние сборы и дорогу до работы.
Типичное рабочее утро писателя начинается с кружки крепкого кофе и обновления локальной копии из SVN. Нужно загрузить к себе изменения, которые другие писатели сделали за прошлый день. У читателя, не знакомого с нашей профессией, может сразу возникнуть вопрос: что же писатели хранят в SVN, ведь это не программисты, исходников у них нет. В том-то и дело, что есть. Об этом нужно рассказать подробнее.
Один в поле не воин
Часто думают, что технический писатель — это профессия, не требующая особых коммуникативных навыков. На практике оказывается, что для написания документации каждый день приходится консультироваться со множеством коллег: бизнес-аналитиками, разработчиками, тестировщиками. Бывает так, что в исходных документах авторы что-то опускают, что-то недоговаривают. Работа писателя — быть профессиональным занудой: уточнять, переспрашивать, перепроверять информацию много раз, чтобы правильно всё описать и не допустить ошибку в документе. Бывают случаи, когда писатели находят ошибки в реализации. Писатель выполняет свою работу на самом последнем рубеже перед отгрузкой системы и документации заказчику.
Квесты и ситуации
Вместе с командой дизайнеров и скриптеров мы обмозговываем и записываем все возможные ситуации в игре, соотнося каждую игровую область с сюжетным поворотом или темами, разработанными в основной истории. Таким способом, мы участвуем в каждом задании от NPC, загадке и полученной награде, в каждом закрученном ходе, который будет открыт дальше по сюжету.
Каждый отдельный квест или ситуация назначаются определенному писателю и скриптеру для совместной реализации. Мы плотно работаем вместе, в паре разрабатывая, как именно ситуация будет структурирована и как вдохнуть в неё жизнь. Мы обсуждаем по скайпу то, как все будет разыграно, затем скриптер воссоздает всю ситуацию на нашем игровом движке с нуля, позволяя затем писателю начать создавать диалоги. В конце концов получается славное маленькое творение от писателя и скриптера, что-то, что может быть плодом только этих двух разумов, работающих в унисон. Когда процесс слаженный, он ощущается как настоящий триумф командной работы.
Клиент всегда прав — отгрузка до 23.59.59
После проверки мы отгружаем документы заказчику. Документы на систему мы отгружаем одновременно с передачей готовой системы. Новые версии ранее отгруженных документов мы, по сложившейся традиции, передаём в пятницу. Документацию мы пока отгружаем в формате PDF — вместе с новой версией системы заказчик получает пакет файлов. Их можно скачать на специальном портале, где каждому заказчику доступна документация по тем системам и их версиям, которые у него установлены. Кстати, нашей документацией пользуются не только заказчики: многие сотрудники компании Bercut тоже обращаются к нашим документам, чтобы разобраться в каком-то сложном вопросе по функционированию той или иной системы.
Бэкграунд
Меня зовут Александр Клименков, я — ведущий технический писатель, кандидат технических наук по специальности «Системный анализ, управление и обработка информации», закончил Санкт-Петербургский электротехнический университет («ЛЭТИ»). В компании Bercut работаю более 5 лет, очень люблю свою профессию. До прихода в Bercut работал преподавателем, техническим писателем и ведущим бизнес-аналитиком.
Что мы делаем?
В Larian я уже два года и ни один день не был похож на предыдущий. Черт, да даже двух часов не было похожих друг на друга! Я стараюсь очень жестко распределять время, чтобы задачи с наивысшим приоритетом были сделаны первыми ежедневно, но это не всегда просто. Наша команда писателей постоянно жонглирует таким количеством задач, что найти на все время довольно сложно. Это хаос, но все работает!
За годы совместной работы мы, если можно так выразиться, стали чем-то вроде коллективного бессознательного, работая наиболее эффективно как неутомимый и питающийся душами монстр Франкенштейна, нежели группа индивидуальностей. Мы смешиваем и сверяем нашу работу постоянно, чтобы добиться наилучшего результата.
Вот лишь несколько направлений нашей ежедневной работы:
На поверку становись!
Когда писатель завершает работу над документом, он обязательно отправляет его на проверку. Документацию проверяют бизнес-аналитики, разработчики, тестировщики. Это очень важный этап, ведь писатель всегда может ошибиться — что-то неправильно понять, не учесть каких-то незадокументированных особенностей реализации.
Ещё наши документы проверяет наш профессиональный технический редактор. Он исправляет орфографические и грамматические ошибки, подчищает описки, следит за смысловой и логической чистотой документа, проверяет соблюдение руководства по стилю. Это руководство — наш маленький внутренний стандарт. В нём записаны разрешённые и запрещённые термины, правила оформления документов разных типов, приведены наиболее часто используемые фразы, конструкции и обороты. Руководство по стилю помогает нам писать документацию по общим для всех писателей правилам: единство стиля — прежде всего. В воображении читателя должен возникнуть собирательный образ одного крутого профессионала — писателя, который создаёт разные документы или разделы.
Персонажи
Мы описываем характеры всех персонажей в игре, начиная от их светлых рождений и заканчивая тяжелыми и жестоким смертями. Это относится к персонажам игроков и их компаньонам и к каждому NPC в игре.
Для важных персонажей мы создаем страницу за страницей истории их личностей. Что движет ими? Что задело их настолько, что сформировало их подход к миру и другим людям, как они действуют в опасности? А в любви? В дружбе? Как нить их истории вплетается в полотно всего сюжета? Затем, чтобы увидеть, насколько они похожи на настоящих людей, мы садимся за стол и отыгрываем каждый их ответ в зависимости от различных ситуаций. После этого достаточно прочные личности, которые проходят нашу “зачистку”, часто оказываются совсем отличными от их оригинальных версий.
Что касается менее важных персонажей, мы все равно стараемся придать им изюминку. Даже если это всего лишь торговец с дороги с одной репликой. Мы пытаемся каждому существу в нашем мире придать некий штрих, который сделает его уникальным по сравнению с остальными персонажами.
Конечно, в процессе создания персонажей мы вдохновляемся окружающим нас миром. Так что если вы увидите какого-нибудь чудака в углу бара, смотрящего на вас пристально, — это вполне может быть один из нас, изучающий, например, ваш уникальный способ заглаживать волосы назад. Я черпаю много идей для персонажей, наблюдая на пассажирами автобуса, на котором еду на работу.
Что дальше?
Дальше — проверять полезность и качество документации, создавать и дополнять стайлгайды, развивать техписателей и повышать общую осознанность компании по теме текстов.
Привет, Хабр! Это снова Larian Studios. Нас очень тронул теплый прием и интерес, оказанный жителями Хабра нашей прошлой публикации, и поэтому, не теряя времени, мы решили написать что-нибудь еще.
В этот раз слово возьмет святая святых наших студии — отдел писателей и сценаристов. Так как по-русски они говорят еще не очень хорошо, я послужу переводчиком статьи, написанной специально для Хабра нашей писательницей Charlene Putney alphachar.
Charlene описала, из чего состоит жизнь сценариста в игровой студии, и зачем вообще они нужны и чем занимаются.
Так как это текст о писателях — картинок будет мало, а букв много.
«Писать на самом деле очень просто. Ты просто садишься перед пишущей машинкой и начинаешь истекать кровью.»
Эрнест Хемингуэй
Привет, Хабр! Меня зовут Шарлин и я — член команды писателей в Larian Studios. Сейчас мы работаем над сюжетом, персонажами и диалогами в Divinity: Original Sin 2. Да, это лучшая работа в мире! Сегодня я расскажу немного о том, что мы делаем, как мы это делаем и почему писатели — важная часть любой серьезной команды игровых разработчиков.
Читайте также: