зачем нужны технические писатели
Техническая документация в разработке ПО: кто, зачем, когда и как описывает проект
Привет! Меня зовут Даша Григорьева, я технический писатель в компании 65apps. Мы занимаемся разработкой сложных мобильных решений, и моя задача — подготовка технической документации по проектам. Очень часто роль технического писателя бывает недооцененной в компании (не у нас, конечно). Поэтому я хочу рассказать, зачем компании-разработчику нужен такой специалист, что такое технический проект, чем он отличается от ТЗ и почему это все необходимо для разработки мобильного приложения.
Общаясь с большим количеством компаний, я все еще встречаю твердое убеждение в том, что написание технического задания для разработки ПО — пустая трата времени и денег. Мы в 65apps считаем иначе. Поэтому приведу несколько аргументов в пользу технической документации и расскажу, кто и как ее пишет.
Техническая документация позволяет оценить стоимость разработки и согласовать функциональность будущей системы. При возникновении споров о стоимости и сроках разработки той или иной фичи она может стать определенной гарантией для заказчика. С другой стороны, если возникнет потребность в развитии приложения, документация облегчит процесс доработки и даст четкое понимание, возможно ли встроить новую функциональность в существующую систему.
Другой пример — государственные организации или организации, чья деятельность ограничивается или подчиняется законам и надзорным органам. Они обязаны осуществлять разработку ПО по всем правилам и с соблюдением всех стандартов. В таких проектах техническая документация, подготовленная по ГОСТам, — необходимое условие.
И разумеется, грамотно составленная и актуальная документация необходима для того, чтобы каждый участник в процессе разработки мог обращаться к документам, если возникают вопросы по конкретной задаче или по всей системе в целом.
Техническое задание и технический проект — два разных документа. Техническое задание отвечает на вопрос «что нужно сделать?», его составляет аналитик в самом начале проекта. Технический проект разрабатывает технический писатель. Этот документ создается после ТЗ и отвечает на вопрос «как нужно делать?».
Кто пишет техническую документацию
Обычно разработкой ТЗ занимается аналитик. Именно он общается с заказчиком / заинтересованным лицом и выявляет у него требования. В сложных случаях к процессу можно привлечь менеджера проекта, разработчиков, тестировщиков и других специалистов. Чем сложнее проект — тем больше требований к документации. Серьезные заказчики из крупных корпораций и госсектора требуют составлять документацию в соответствии с ГОСТами, а это задача очень трудоемкая, требующая внимательности к деталям и постоянной вовлеченности в процесс. И это не только ТЗ, но и технический проект, полностью описывающий все используемые в разработке решения, подходы и методологии. На него также распространяются ГОСТы. Подготовкой такой документации должен заниматься специалист — технический писатель.
Для крупных проектов иметь в штате технического писателя просто необходимо. Разработка решений для крупных заказчиков может длиться год и более, это довольно долгий срок. За это время возникает достаточное количество изменений, провоцирующих обновление документации. Кроме того, любая долгосрочная разработка ПО предполагает развитие. В этом случае актуальная техническая документация позволит снизить риски, закладываемые в работу исполнителей.
Исключение может быть сделано для представителей госсектора. Таким организациям необязательно иметь в своем штате специалистов соответствующего профиля, так как при возникновении необходимости всегда можно обратиться к профессионалам, которые выполнят качественно свою работу.
Кто такой технический писатель
Строго сформулированного перечня должностных обязанностей технического писателя не существует: каждая компания формирует его сама, а иногда возлагает на такого специалиста и дополнительные задачи. Поэтому иногда бывает сложно даже определить род деятельности технического писателя. В нашей компании такой специалист составляет документацию, необходимую для дальнейшей разработки программного обеспечения.
Для этого он собирает информацию и материалы от участников проекта и документирует эти данные согласно требованиям заказчика, в том числе и в соответствии с ГОСТами. Речь идет о ГОСТ 19 «Единая система программной документации» и ГОСТ 34 «Информационная технология. Комплекс стандартов на автоматизированные системы». Также технический писатель следит за актуальностью технической информации, если это необходимо на длительных и сложных проектах.
Какая техническая документация нужна разработчику
Рассмотрим идеальный с точки зрения ГОСТа процесс разработки системы.
Все начинается с требований заказчика или заинтересованных лиц, которые необходимо выявить и обязательно зафиксировать в документе «Техническое задание».
Техническое задание — это документ, регламентирующий бизнес-цели, общее описание системы, объем работ, границы проекта, а также порядок разработки, оценки и приемки. Данный документ отвечает нам на вопрос «что нужно сделать?» и фактически является постановкой задачи.
Аналитик составляет ТЗ и согласует его со всеми заинтересованными сторонами. После того как собраны и утверждены все требования, можно приступать к созданию прототипов будущей системы и разработке программного обеспечения.
На этом этапе начинается разработка макетов, сценариев, архитектуры и др. Раз уж мы говорим об эталонном процессе разработки, то все это должно быть описано в техническом проекте, который также использует часть информации из ТЗ.
Технический проект — это совокупность документов, описывающих и обосновывающих все подходы, методы, архитектурные и технические решения, применяемые для создания системы. Например, в технический проект включают макеты интерфейсов, описание протоколов для интеграции со смежными системами и оборудованием, пользовательские сценарии, описание алгоритма и их формирование, структура серверов и баз данных, а также другие требования к системе и ее взаимодействию с другими внешними системами.
это далеко не все: существует много стандартов для написания технической документации, и для каждой страны они свои. В отечественных стандартах есть отдельно ГОСТ на создание автоматизированных работ и на программное изделие. Например, технический проект по ГОСТу 19 «Единая система программной документации» может включать в себя следующий перечень работ:
Теперь, когда есть четкое понимание архитектуры, функциональности и дизайна проекта, можно перейти к разработке системы и ее тестированию.
На этапе тестирования, помимо проверки работоспособности системы, проверяется также выполнение всех требований, зафиксированных в документах, что позволяет разрешить спорные ситуации с заказчиком.
Когда составлять техническую документацию
Выше я описала идеальный процесс создания программного обеспечения, но иногда некоторые документы технического проекта составляют уже после этапа разработки.
Есть проекты, в которых важно иметь полную документацию до начала работ. Это касается решений с высокими требованиями к безопасности, соблюдению законодательства и т. д. Например, мобильные приложения для банков. В этом случае важно сначала продумать все детали системы (информационная безопасность клиентов и самого банка, соответствие законам). На это уйдет больше времени, но позволит избежать финансовых и репутационных рисков.
Если разработка идет по методологии Agile, то нет смысла прописывать всю документацию до старта работ. Если заказчику важно работать по спринтам и контролировать ход разработки, документацию можно дописывать параллельно основному процессу.
В нашей компании возможны оба варианта — мы умеем адаптироваться под условия и пожелания заказчика.
На сегодняшний день технический писатель не самая распространенная специальность, но для серьезной компании-разработчика такой сотрудник не менее важен, чем, например, аналитик.
Техническая документация обязательно разрабатывается для госзаказчиков, она необходима и для долгосрочных проектов, на которых с бОльшей вероятностью могут меняться подрядчики. Имеет смысл создавать технический проект для ноу-хау технологий и проектов высокой сложности — документация понадобится отделу QA, чтобы отличить баги и фич.
Профессия технический писатель
Это хорошая профессия для людей, желающих работать на стыке технического и гуманитарного направлений. В отличие от копирайтинга, здесь меньше творчества и больше регламентов. В данной статье мы расскажем, кто такой технический писатель и что входит в его обязанности, как стать таким специалистом и где искать работу, в том числе удаленно.
Содержание статьи:
Кто такой технический писатель и чем он занимается?
Технический писатель – это специалист, который создает документацию к программам, интернет-сервисам, оборудованию и устройствам. Это могут быть как документы для инженеров и разработчиков, так и руководства для пользователей. Например, инструкция к смартфону, ноутбуку, метеостанции.
В функции технических писателей входит подготовка ТЗ, руководств, инструкций и других документов. По ним люди, которые будут пользоваться программами или оборудованием или участвовать в их доработке, смогут разобраться, что и как устроено и как работает. Технический писатель – это профессия, которая требует ответственности.
В должностные обязанности технического писателя входит:
Подготовка отчетов о проделанной работе.
Иногда в обязанности технических писателей включают работу над интерфейсами, локализацию. Например, необходимо перевести интерфейс программы с английского языка. Технический писатель подбирает термины на русском языке, которые наиболее близки к оригиналу, чтобы пользователи поняли, где и какие функции находятся.
Также в функции технических писателей включают подготовку простых графиков и диаграмм, скриншотов, учебных видео материалов. Иногда им поручают создание статей и рекламных материалов, хотя эту работу должен выполнять копирайтер.
Плюсы и минусы профессии технического писателя
Развивает системное мышление.
Сложности в карьерном росте. Если вы не желаете работать на руководящих должностях, это не будет для вас минусом.
Сколько зарабатывают технические писатели?
Зарплата начинающего технического писателя начинается от 40 тыс. руб. в месяц. Средняя зарплата специалиста с опытом 2-3 года – 60-80 тыс. руб. в месяц. Специалисты, создающие документацию на английском языке, могут получать больше 150 тыс. руб. в месяц. Например, так платят в ИТ-компаниях, которые создают софт для западных рынков.
Технический писатель может работать как в офисе, так и удаленно, а также быть фрилансером. Средние цены на создание технической документации – от 500-1000 руб. за страницу (1800 знаков с пробелами). Например, разработка технического задания у фрилансера может стоить от 20 тыс. рублей, руководства для администратора – от 25 тыс. рублей. При заказе в компаниях эти документы будут стоить в 2 раза дороже.
Что должен знать и уметь технический писатель?
Желательно знать английский язык.
Как стать техническим писателем с нуля?
В эту профессию приходят двумя путями. Первый – человек с техническим образованием понимает, что разработка и проектирование – это не его. Решает вместо работы инженером попробовать себя в новой сфере. Второй путь – человек с гуманитарным образованием желает работать в технической сфере, но не программировать. Тогда он становится писателем.
Если вы новичок, то можете поискать вакансии с минимальными требованиями на HH.ru. Например, для создания онлайн-справок могут взять человека без технического образования и опыта. Так вы сможете постепенно погружаться в предметную область, осваивать новые задачи и профессионально расти.
Бесплатные курсы для технический писателей проводятся в Академии Гипербатона от компании Яндекс. Обучение занимает 1 месяц. Для поступления необходимо справиться с тестовым заданием. Лучшим выпускникам могут предложить работу.
Будет полезно читать книги, например, «Разработка технической документации» Вадима Глаголева. Это справочник, в котором собраны ссылки на ГОСТы и выдержки из них.
Много информации для начала карьеры в профессии можно найти на форуме технических писателей Techwriters.ru и на YouTube.
Где искать работу?
Посмотрите открытые вакансии в местных ИТ-компаниях, интеграторах, разработчиках софта. Часто они набирают стажеров, которых потом могут брать в штат.
Зачем нужны технические писатели
Авторизуйтесь
Зачем нужны технические писатели
Текст как призвание
Уже много лет я работаю техническим писателем в крупной IT-компании. До этого мне приходилось заниматься и тестированием, и программированием, и преподаванием, затем больше пяти лет отработал ведущим бизнес-аналитиком. Но я вернулся в писатели, и в этой статье я расскажу, почему.
В умных книгах по саморазвитию часто пишут, что заниматься любимым интересным делом — это один из главных способов избежать профессионального выгорания. Работе с системами и текстами я посвятил уже почти 25 лет, и могу с уверенностью сказать, что профессиональное выгорание — это не про меня. Моя специальность позволяет мне постоянно развиваться в разных направлениях, каждый день учиться чему-то новому, даже много лет проработав в одной компании.
В мире разработки систем и ПО всё постоянно меняется — появляются новые технологии и отрасли, у систем появляются новые функциональные возможности. Но всегда будут нужны те, кто сумеют во всём этом разобраться и написать простой понятный текст для пользователей системы. Я уверен, что в ближайшие десятилетия профессия технического писателя не только останется нужной и востребованной, но будет обретать всё большую популярность и ценность на рынке.
Текста больше, чем кода
— Кто за сутки до отправки заказчику во всей инструкции заменил manual на manul?!
Давайте окинем взглядом весь процесс разработки программного обеспечения. Его главный результат — это, конечно, программный код. А его главными действующими лицами всегда были и будут программисты, что бы там ни говорили другие его участники.
Но сам этот процесс попутно порождает большое количество текстовых артефактов. Тут и функциональные требования заказчика, и техническое задание, и многочисленные протоколы совещаний, и переписки в чатах, и комментарии к запросам в системе планирования задач, и, наконец, описание реализации. А ведь есть ещё многочисленные комментарии в коде, которые тоже содержат много нужной информации.
В общем, текстов хватает. Так зачем же тогда в самом конце разработки нужен ещё и технический писатель? Почему всех этих документов недостаточно для того, чтобы дать ответы на основные вопросы заказчика и пользователя: как работает система и как её настроить?
Разработчики должны писать код, а не текст
«Условие, что поле PART должно быть не пустым, обеспечивается целостностью процесса, заполняющего это поле, и не обеспечивается отдельным ограничением Oracle типа NOT NULL для обеспечения максимального быстродействия при изменении данных таблицы».
Из внутренней документации проекта
Бывает так, что программисты прекрасно разбираются в программе, досконально понимают все тонкости работы системы, но не могут красиво изложить всё это в текстовом виде. Лично я убеждён, что в этом нет ничего плохого.
Согласитесь, что даже текст, написанный с орфографическими и стилистическими ошибками, может быть понятным и успешно выполнять свою функцию — доносить до читателя мысль автора. А ошибки — это дело поправимое, коррекцию и правку текста при необходимости может выполнить редактор или тот же технический писатель. Главное — не допускать ошибок фактических.
Каждый должен заниматься своим делом. Например, математику или физику часто проще написать формулу, чем объяснить словами какой-то закон. Программисту проще выражать свои мысли в виде кода и алгоритмических конструкций.
Когда же дело доходит до формулирования чётких и понятных текстов на русском (или другом) языке, в дело вступает технический писатель. Это тот самый специалист, который переводит информацию с языка разработчиков на язык пользователей. Не было бы технических писателей, и программистам пришлось бы самим напрягаться, пытаясь объяснить такие понятные и очевидные для них вещи обычным пользователям системы.
Стройная система подпорок и противовесов
Хогвартс напоминает любой IT-проект, который разрабатывается долгое время. Древние баги, нигде не прописанные фичи, несовместимости, куча сдерживающих этот ужас костылей и несколько программистов, которые даже не хотят лезть в неведомые глубины и гордо называют их «школьными традициями».
bash.im
К сожалению, большинство современных программных систем автоматизации бизнес-задач имеют очень сложную и запутанную внутреннюю структуру. Мы уже привыкли и считаем нормальным, что у наших программ есть много недокументированных возможностей.
Если система живёт и развивается уже несколько лет, то в ней с каждым годом появляется всё больше исключений из правил. В неё добавляются новые функциональные возможности, старые отмирают или видоизменяются. Настройка системы становится всё сложнее, в интерфейсе появляется всё больше параметров, которые взаимодействуют друг с другом неочевидным и зачастую непредсказуемым образом.
Постоянная гонка за быстрой реализацией новых бизнес-возможностей приводит к тому, что сокращается время на рефакторинг старого кода и устаревших интерфейсов. Так и остаются в системе старые и недействующие параметры и настройки.
Представьте, каково пользователям работать в такой «пожилой» системе без сопроводительной документации, которую пишут технические писатели. Это всё равно, что управлять атомным реактором, не прочитав предварительно многотомное руководство по интерфейсу пульта управления. Как говорил Гомер Симпсон: «На такую-то кнопку так сразу и не нажмёшь».
Внутренние документы по системе, порождённые в процессе разработки, представляют для пользователя неразрешимую головоломку. Без пользовательской документации он просто «утонет» в многочисленных описаниях итерационных изменений, выполненных в различных местах системы.
Задача технического писателя — всё это объединить, систематизировать, структурировать и изложить понятным пользователю стандартизированным языком. Кстати, бывает, что аналитики, разработчики и тестировщики сами с трудом ориентируются во внутренней документации. Чтобы быстро найти ответ на свой вопрос они часто пользуются документацией, написанной техническими писателями. Ведь там всё аккуратно разложено по полочкам, структурировано и систематизировано.
Нажми на кнопку — получишь непонятный результат
«Клавиша имитации ручки выполняет переключение из исходного меню в меню ручек управления, которое позволяет выполнить функции ручек управления с помощью клавиши».
bash.im
Давайте ещё немного поговорим об интерфейсах. Техническим писателям часто приходится описывать поля в окнах приложений. Обычно это списки из пар «Название поля — описание». Если нам нечего добавить к названию поля, мы понимаем, что интерфейс спроектирован хорошо, а логика работы системы проста и понятна. Это характерный показатель того, что название поля полностью описывает его назначение и никаких исключений и особенностей в его работе нет.
Но, к сожалению, так бывает редко. Чаще нам встречаются объекты с непонятным названием и назначением. Сколько раз мне приходилось описывать поля с названием «Дата начала» или просто «Дата»!
Вот признаки плохого интерфейса, которые сразу видны техническому писателю:
Мне приходилось описывать интерфейсы, в которых на одной панели рядом было расположено несколько кнопок с одинаковыми пиктограммами и разным назначением. В таких случаях писатель вынужден конструировать пассажи вроде такого: «Чтобы создать запись, нажмите первую кнопку [+] на панели инструментов таблицы в левом верхнем углу окна».
Но даже если интерфейс спроектирован хорошо и качественно, в сложных системах всё равно будет требоваться его описание. Хотя бы для того, чтобы внятно объяснить пользователю, почему ему недоступно для редактирования то или иное поле. Или чтобы составить списки доступности просмотра и редактирования полей в зависимости от роли пользователя.
Изъян привёл к конфузу
Решили, что «баг» — это «изъян», а «инцидент» — «конфуз».
bash.im
Каждая сложная система имеет свою разветвлённую структуру понятий, объектов и процессов. Думаю, излишне говорить, что для достижения нормального взаимодействия между всеми участниками процесса разработки, они должны использовать единую терминологию. Если же терминология размыта, один и тот же объект может называться по-разному, то договориться будет очень сложно. Для того, чтобы достичь единства в этом вопросе, в компании должен существовать единый глоссарий терминов.
Простой пример: один и тот же объект во внутренних документах может называться «системным параметром», «параметром системы», просто «параметром» или даже «записью в таблице параметров». Для разработчиков системы может быть понятно, что всё это — один и тот же объект. Для пользователя же это совсем не так очевидно. Может быть, после некоторого размышления, он догадается, что все эти названия описывают одно и то же. Но мы же любим наших пользователей, зачем постоянно заставлять их решать подобные головоломки?
Есть ещё одна важная особенность технических текстов: кроме правильного употребления общих терминов важны также фигуры описания. Так называются повторяющиеся фрагменты небольшого размера — словосочетания или короткие простые предложения. Например:
Для фигур описания иногда составляют отдельные словари или справочники. Казалось бы, мелочь. Но пользователь привыкает к определённым конструкциям и фразам. Если в одном месте документа написано «Выберите режим», а в другом «Перейдите в режим», у пользователя может возникнуть сомнения: здесь описано одно и то же действие или разные?
Задача технического писателя — унифицировать весь тот зоопарк формулировок и терминов, которые употребляют в своих документах аналитики, разработчики и другие участники процесса разработки ПО. У технических писателей обычно есть свои словари терминов и фигур описания. Опытный писатель разбирается в системе и понимает, что именно означает тот или иной жаргонный термин во внутреннем документе.
Вратарь разработки
Технический писатель — лучший гуманитарий среди технарей и лучший технарь среди гуманитариев.
Михаил Острогорский
Выходит, что технические писатели в пользовательской документации исправляют все недостатки, ошибки и неточности, допущенные во внутренней документации и метаданных в процессе проектирования и разработки системы. Это тот самый рубеж, на котором «баг» (то есть «изъян») волшебным образом превращается в «фичу», а «велосипеды» и «подпорки» — в стройную архитектурную схему из красивых разноцветных прямоугольников.
Как известно, программист — это не тот, кто пишет программы, а тот, чьи программы работают. Точно так же технический писатель — это не тот, кто пишет технические тексты, а тот, чьи документы помогают пользователю решить проблему или найти ответ на вопрос.
Раньше разработку пользовательской и эксплуатационной документации могли взвалить на программистов, хотя это совсем не их обязанность. За написание документации могли посадить и специалиста с гуманитарным образованием, который в совершенстве владеет родным или иностранным языком, но при этом обычно совершенно не разбирается в предмете описания. Обычно при таком подходе, хороший итоговый результат мог получиться разве что случайно. Теперь в каждой достаточно крупной компании по производству ПО есть свои технические писатели, которые одновременно хорошо умеют разбираться в сложных технических системах и писать понятные тексты на нужном языке.
Спрос на хорошую, качественную документацию к программам и системам постоянно растёт. При этом, по моим наблюдениям, сейчас на рынке наблюдается недостаток профессиональных технических писателей. Мы как раз находимся в активном поиске новых писателей в нашу команду и ощущаем этот дефицит в полной мере — опытные технические писатели сейчас на вес золота.
Во всём мире профессия technical writer (или technical author) считается престижной и перспективной. Спрос на технических писателей обычно превышает предложение. Многие переходят в технические писатели из других профессий — переводчиков, аналитиков, даже программистов. У нас интереснее!
Техническое документирование — это одна из замечательных пограничных областей для тех, кто так и не смог смириться в школе с разделением на гуманитариев и математиков. Есть такие люди, которым скучно просто заниматься железками или программами, им не хочется ограничивать себя сугубо инженерными специальностями. В то же время они не могут жить вдали от техники и современных технологий. Именно поэтому я так люблю свою профессию — мне никогда не будет скучно, я постоянно могу развиваться и совершенствоваться в разных направлениях — как технических, так и гуманитарных. Каждый день я могу привносить ещё немного порядка в сложный и запутанный мир технологий, систем и программ.