Технический писатель - летописец от мира IT? Часть 2
Екатерина Валерьевна Каляева – выпускница программы "Фундаментальная и прикладная лингвистика", сохраняющая связь с программой уже в роли преподавателя. Кроме того, Екатерина Валерьевна — технический писатель, отвечающий за создание и поддержание технической документации (документов, которые объясняют, как работает продукт), а также UX-писатель, который фокусируется на создании удобного пользовательского интерфейса. В этой части интервью вы узнаете о том, что поможет разобраться в профессии, какие лайфхаки есть у технических писателей и даже о том, можно ли совместить эту работу с преподаванием
Первую часть интервью Екатерины Валерьевны о задачах и навыках технического писателя можно прочитать по ссылке.
Фишки технического писательства: как добиться понятного текста?
- Как вы рассказали, одна из важных задач технического писателя – создавать понятную документацию в проекте, описывая сложные технические процессы. При этом документация может быть внутренней – для работы команды, и внешней – для пользователя. Как вы передаете информацию так, чтобы она была понятна читателю? И насколько важно для усвоения информации пользователем приводить примеры работы кода?
Эволюционно в развитых уже командах уже существуют свои наработки и договоренности о том, как мы пишем, они берутся из общей практики, когда мы уже много чего написали, попробовали по-разному. Очень важно таким правилам следовать, но при этом критически смотреть и быть гибким, искать все время какие-то новые способы улучшить понятность.
А вообще понятность не никак не измерить. Существуют какие-то метрики понятности, они рассчитываются в цифрах, но все равно это немножечко искусственно. Поэтому больше решает практика, обмен опытом с другими техническими писателями, и нужно все время держать ухо востро, смотреть критически.
- Получается, что эту простоту и понятность определяете непосредственно вы, ваши коллеги и те, кто ставит перед вами эту задачу?
Да, есть еще важный момент. Документация, прежде чем быть опубликованной, открытой для пользователей, проходит два этапа ревью. Первое ревью – от экспертов предметной области, от того человека, которого ты интервьюировал. Он должен посмотреть, что ты не искажаешь факты. Второй этап ревью происходит с другой стороны, это ревью от технического писателя не с твоего продукта — на этом этапе уже не важны знания о продукте, а важно соответствие общим практикам, договоренностям и гайдам редакционной политики. За счет этих двух этапов ревью мы получаем достаточно качественную документацию на выходе.
- Поделитесь своими фишками, как посмотреть на свой текст свежим взглядом?
По возможности отложить написанный текст хотя бы на пару часов, лучше до следующего дня. Чем это полезно? Тем, что за это время очищается оперативная память, утро вечера мудренее. Следующая практика — это чтение с конца. Когда мы читаем текст как обычно, мы не обращаем внимание на какие-то мелкие ошибки, потому что мозг сразу хочет построить целостный опыт, то есть получить от этого текста концепцию, идею. А когда мы читаем с конца, то мы читаем по слову, и как раз можем увидеть опечатки.
- Вы имеете в виду именно чтение справа налево по словам?
Да, с конца текста. Также я очень приветствую всякие технические средства, чтобы снять с себя часть нагрузки: какие-то встроенные или внешние инструменты проверки опечаток, ошибок. Например, у Главреда есть онлайн-инструмент, который оценивает, насколько твой текст канцелярский, есть ли в нем вода, и ставит оценку, подчеркивает эти нарушения.
Есть еще один важный способ, как можно проверить смысловую адекватность текста. Попробовать представить, что ты его даёшь либо пятилетнему ребёнку, либо своей 80-летней бабушке, и оценить, насколько обе эти крайности его поймут. Здесь мы не стремимся к тому, что и ребёнок, и пожилой человек все поняли на сто процентов. Но такой подход может отрезвить, что где-то, возможно, слишком сложно, или где-то не хватает контекста или примера для полного понимания.
В вузе и за его пределами: как совмещать профессии?
- Помогает ли техническое писательство в преподавании? И если помогает, то каким образом?
Самое главное пересечение в том, что мне как техническому писателю с прокачанными навыками структурирования информации и умением ее подать под определенную аудиторию проще составлять конспекты пар, выстраивать темы в определенном порядке и взаимодействовать с аудиторией.
- Есть и обратный вопрос: помогает ли преподавание в техническом писательстве?
Здесь сложнее ответить, но в целом преподавание — это какая-то потребность души. Когда я училась в универе и видела, что у нас достаточно много молодых преподавателей, которые при этом работают в сфере IT, и из которой нам рассказывают что-то, появилась мечта быть на их месте.
Я думала, вау, как круто, что они практикующие специалисты и они нам рассказывают актуальные вещи из их сферы. Преподавать и передавать знания — это моя внутренняя потребность, я ее удовлетворяю, чувствую себя более счастливой и реализованной, и от этого у меня как будто больше энергии делать мою работу технического писателя.
- Чувствует ли преподаватель себя более востребованным, если он работает в той сфере, в которой он преподает?
Здесь я могу сравнить себя с собой. Преподаю в Вышке уже три года, из них в первый я вела сложный предмет у старшего курса, сама не находясь в глубоком погружении в сферу. Из-за этого включался синдром самозванца, не было уверенности, что я могу дать что-то новое и уникальное, преследовало ощущение, что я не на своем месте.
Поэтому я перешла к младшим курсам, к тому времени уже как раз и стала работать в продукте, связанном с МL, в этой сфере. И вот здесь уже я почувствовала, что внутри стыкуется больше, и какой-то пользы получается тоже больше, по ощущению.
- Помогает ли преподавание не забывать азы, может быть вспомнить что-то важное или поддерживать себя в тонусе относительно определенных знаний?
Да, конечно. Когда ты долго в практике профессии, то базовые теоретические моменты уходят, потому что на работе ты не занимаешься чтением теории, ты решаешь практические задачи. И вот спустя время навык нарабатывается до степени автоматизма. Потом, когда ты сталкиваешься с какой-то новой проблемой, где ещё нужно подумать, как её решить, тебе бывает полезно вспомнить какие-то теоретические принципы, подходы. Поэтому да, конечно, это помогает.
Советы и лайфхаки: что поможет начать путь в профессии?
- Что вы считаете самым важным при составлении резюме?
Обязательно пишите резюме в терминах результатов, лучше с цифрами. Вы что-то делали с такого по такой период, добились того-то, это так-то повлияло на бизнес — примерно такая формула. Еще важно указывать только релевантный опыт — то есть в идеале под каждую вакансию резюме немножко подкручивать. Для навыков я обычно прописываю, на каком уровне владею, какие примерно задачи могу решить, и не страшно, если это начальный. Например: "git: могу разрешить конфликт и посквошить коммиты".
- Насколько сейчас эффективны онлайн-курсы для получения профессии в айти?
Стоит понимать, что ничего не даст нам профессию, кроме как опыт работы внутри этой профессии. Курсы — хороший инструмент, подходит для тех, у кого ограничено время или кто не хочет сам искать информацию. Я, кстати, тоже по курсам люблю учиться, мне нравится взаимодействовать с опытным наставником в вопросе. И еще наблюдение из жизни: говорят, что лучше проходить курсы от небольших компаний, где еще не поставлено на поток получение прибыли, и есть шанс, что учат с душой
- И наконец, какие источники (курсы, литературу, видео-уроки) вы считаете необходимыми, ключевыми для технического писателя?
Неизменно уже много лет новичкам рекомендую бесплатный или платный экспресс-курс от documentat. Моя настольная книга — Нора Галь "Слово живое и мертвое", поможет писать яснее и чище. Это тот же Ильяхов, но без выкрутасов и на 50 лет раньше. Сейчас еще много у кого есть телеграм-каналы, рекомендую, например, лида писателей в Озоне Катю Ушакову.
Более узкие специфичные рекомендации:
Еще можно почитать про docs-as-code, научиться писать документацию API и подтянуть навык «писать понятно и просто».
Автор: Евгений Баронов, 22ФиПЛ