СМИ о нас
Чем занимается
технический писатель:
опыт IT-компании Lad
Время чтения: 8 мин 39 сек
02 Августа 2021
Поделиться статьей
Подпишитесь на рассылку
Рассказывают технические писатели IT-компании Lad Екатерина Каляева, Анна Назолина, Ксения Скорынина.
Когда нас спрашивают, в чем заключается работа технического писателя, на ум приходит сразу несколько ответов. Конечно, проще всего сказать: мы пишем документацию. Но теоретически документацией можно назвать практически всё, что угодно: от треда в рабочем мессенджере до технического задания размером в сто страниц. Поэтому стоит конкретизировать, какую документацию, для кого и как мы создаем.
Технические писатели и knowledge management
Технические писатели в компании выполняют разную работу. Например, часть команды занята в сфере управления знаниями внутри проектных групп. Она не привязана к единственному продукту или команде, а занимает позицию как бы вне конкретного проекта и готова подключиться к любому из них. Основная единица документации — статья в базе знаний. Статьи объединяются в проекты, при этом их внутренняя структура одинакова.
Так выглядит база знаний Центра Разработки. Слева — проекты и дерево статей, справа — непосредственно тексты статей.
Такой подход позволяет не писать «в стол» или для галочки, а создавать минимально необходимый пул статей для каждого продукта, а затем отслеживать уникальные потребности команды в документации по мере работы над проектом. В то же время технические писатели снижают уровень хаоса и экономят ресурсы других членов команды. Они документируют часто обсуждаемые фичи и процессы, когда проектные команды растут, и люди начинают чаще переходить между проектами. Качественная и актуальная база знаний позволяет снизить порог вхождения для новых членов команды.

Вместо того чтобы объяснять одно и то же разным людям несколько раз, коллегам достаточно один раз рассказать это техническому писателю, а потом давать ссылку на релевантную статью.
Технический писатель по канону
«Классический» технический писатель в компании занимается написанием не только внутренней документации на проекте, но и внешней — для заказчиков.

Внутренняя документация — это, например, описание админки, процесса продажи/возвратов/рассрочки, БД MongoDB. А внешняя обычно включает в себя описание верхнего уровня проекта: цели, требования, бизнес-эффект, а также мануал для работы сотрудников с разрабатываемым продуктом. Таким образом, технический писатель играет важную роль в команде вне зависимости от его специализации. Это не просто сотрудник, который пишет документацию, исходя из своей точки зрения и предпочтений. Техписатель-профессионал может почерпнуть «тайную» информацию от коллег-разработчиков и, что важно, принимает точку зрения каждого из коллег.
О том, почему документация — это непросто
При написании документации мы используем множество источников информации: это и собственные знания, и знания коллег, код, вся ранее написанная документация, если такая есть, и требования заказчиков. Самая важная задача здесь — это побывать в роли каждого сотрудника:

  • менеджера, чтобы понять бизнес-условия и заинтересовать своей документацией;
  • разработчика, чтобы понять, как это должно работать и реализуемо ли;
  • тестировщика, чтобы нащупать все нюансы и продумать разные варианты исходов событий;
  • пользователя, чтобы информация была подана просто и доступно, например, в руководстве или туториале.

Поэтому основная цель при написании документации — отследить все информационное потоки, возникающие во время работы над продуктом. Чем полнее мы их увидим, тем лучше и качественнее получится итоговый документ.
Инструменты must-have
Для создания документации на разных этапах мы используем инструменты, которые облегчают нам работу, помогают видеть прогресс и писать лучше.

  • Slack. С его помощью мы общаемся внутри нашей команды технических писателей и с членами других команд. Мессенджер удобен тем, что каждую новую тему в деталях можно обсудить в отдельном треде. Ребята из команд добавлены в каналы, соответствующие проектам. Это помогает быть в курсе новостей и обсуждений.
  • Google Docs. Этот сервис мы используем, во-первых, чтобы продумать структуру статей или написать их целиком. Во-вторых, для написания технической документации верхнего уровня: мануала для заказчика, описания админки или для создания небольшого объема документации для коллег. Обычно даем доступ к нужному документу другому техническому писателю или коллеге в режиме редактирования, если он хочет добавить контент, или комментирования, если он готов проверить то, что мы написали.
  • YouTrack. Его мы используем в двух случаях. Первый — это доска Agile, где мы пополняем наш бэклог, распределяем задачи между собой, отслеживаем прогресс. Второе — База знаний, куда мы выкладываем наши статьи и проводим ревью статьей от коллег.
  • Confluence. Его преимущества — гибкость, большой выбор инструментов и древовидная структура, позволяющая сразу видеть новые проекты, релизы или требования. Инструменты Lucidchart и diagrams.net позволяют создавать широкий спектр диаграмм, от простых блок-схем до высокотехнологичных сетевых диаграмм, которые активно используют разработчики при переходе к новой функциональности на проекте.
  • Технические писатели не остаются в стороне и от традиционно девелоперских инструментов. Так, для просмотра актуальных или выполненных задач мы используем issue-трекер в Gitlab. Там же читаем сам код, потому что иногда нам требуется описание полей и переменных. А с помощью MongoDB/Rancher можно посмотреть на используемые микросервисы, благодаря чему получается создавать более детальное описание.
  • Последнее, о чем хотелось бы упомянуть, это сервисы Главред и Простым языком, где можно проверить качество своего текста, узнать, есть ли в нем повторы, опечатки, а также уменьшить его «водность».
Как выполнять план без нервов
Каждый день из работы технического писателя — особенный. Иногда мы несколько дней вдумчиво работаем над написанием одной статьи. А порой все горит и появляются новые задачи, которые нужно оперативно решать. Ежедневно мы проверяем доску Agile, оцениваем количество оставшихся задач и их статус. Выбрав приоритетные на день, прописываем их детально в карточке задачи, а затем переносим эти микрозадачи в свой Google-календарь. Так они удобно комбинируются с митингами и другими запланированными мероприятиями. Таким образом удается эффективно распределять свое время и не хвататься за все сразу, а план на день успешно выполняется.
Например, так выглядит календарь технического писателя, который работает в компании около года и уже вовлечен во многие ее проекты.
Жизненные циклы задач
Один из важнейших инструментов технического писателя в нашей компании — это трекер задач YouTrack. В нем у нас есть своя Kanban-доска, на которой мы видим все задачи, которые лежат в бэклоге, находятся в работе, приостановлены или готовы. При помощи флажков мы выставляем задаче приоритет, в некоторых случаях обозначаем дедлайн. Пока мы работаем над задачей, оставляем к ней комментарии о том, что уже сделано, что еще предстоит, важные ссылки и контакты людей, а также ведем обсуждение.
С помощью такой доски удобно менять статус задачи и делать к ней пометки.
Задачи обычно приходят по нескольким каналам. В первую очередь, это техлид Центра Разработки или менеджер проекта. Мы практикуем регулярные встречи с ними, обычно в формате видеозвонка, чтобы обсудить прогресс по задачам: какие выполнены, какие сейчас в процессе, а что вызывает трудности. Другой путь формирования задач — это канал #docs в корпоративном мессенджере Slack. Мы используем его как инструмент коммуникации с командами: этой самый быстрый способ для них спросить технических писателей о чем-то или поручить написание статьи. В том же канале мы объявляем последний новости, связанные с базой знаний, и делаем анонсы статей.
Тон фидбека мы обычно определяем по реакциям в Slack.
И, наконец, третий вариант — техписательская наблюдательность. Мы состоим в миллионе разных каналов по всем проектам компании. С какими-то из них мы работали больше, с какими-то меньше, однако если вдруг мы видим, что ведется обсуждение какой-нибудь фичи или процесса, о которых потенциально будет полезно узнать другим, то подключаемся и предлагаем задокументировать и сложить в базу знаний. Обычно коллеги соглашаются.

Каждая задача проходит примерно одинаковый жизненный цикл. Вначале мы определяем цель и целевую аудиторию статьи. Сформулировав вопросы, отправляемся с этим к эксперту в предметной области (SME), формируем черновик статьи. После нескольких итераций, в течение которых редактируем контент и его представление, мы показываем готовый текст всем заинтересованным лицам. Наконец, документ или статья публикуются, и происходит обсуждение того, как мы будем поддерживать актуальность.
3 сигнала, что задачу можно закрывать
Понять, что задача успешно выполнена, можно по нескольким критериям.

  • SME или тот, кто ставил задачу, проверил текст статьи и посчитал, что мы отразили все детали вопроса.
  • Конечный текстовый продукт устраивает всех стейкхолдеров, которые работали над ним вместе с техписателями.
  • Если конкретного инициатора задачи нет или текст объемный, мы обычно тестируем его на нескольких представителях целевой аудитории. Если мы видим, что текст выполняет свою задачу для респондентов, значит, все получилось и задачу можно закрывать.

Следуя своей тактике, технические писатели IT-компании Lad за полгода обработали около 40 документационных задач и создали свыше 100 статей в базе знаний Центра Разработки.
Источник: https://tproger.ru/articles/chem-zanimaetsja-tehnicheskij-pisatel-opyt-it-kompanii-lad/
Другие статьи из раздела СМИ о нас
07 Октября
СМИ о нас  
Почему обучение технического писателя — это нетривиальная задача
01 Октября
СМИ о нас  
IT-компания Lad помогает бизнесу и государству управлять HR-капиталом
28 Сентября
СМИ о нас  
ООО «Платформа строительных сервисов» — серебряный партнер конференции #ГИСОГД2021
27 Сентября
СМИ о нас  
Проект управления HR капиталом региона представлен на «ПРОФ-IT»
27 Сентября
СМИ о нас  
Список региональных IT-проектов – победителей конкурса «ПРОФ-IT.2021»
27 Сентября
СМИ о нас  
IX Всероссийский форум «ПРОФ-IT» — фотолента
СМИ о нас  
ТВ: На старт благотворительного забега “Открытые сердца” вышли более 200 человек
30 Августа
СМИ о нас  
Топ-17 крупнейших ИT-компаний Нижнего Новгорода
18 Августа
СМИ о нас  
Нижегородская область лидирует по доступности мер поддержки IT-компаний
05 Августа
СМИ о нас  
Прокачиваем анимацию с react-native-reanimated. Часть 1
30 Июля
СМИ о нас  
Пишем свой dependency free WebSocket сервер на Node.js
27 Июля
СМИ о нас  
Сколько стоит рекомендация IT-специалиста в Нижнем. Аналитика
16 Июля
СМИ о нас  
IT-компания Lad вошла в ТОП-5 работодателей по найму Junior-разработчиков
06 Июля
СМИ о нас  
Технический писатель: с чего начать
28 Июня
СМИ о нас  
10 эко-приложений, которые помогают спасать природу
27 Июня
СМИ о нас  
IT-кампус на 7 000 студентов создадут в Нижнем Новгороде
23 Июня
СМИ о нас  
В Нижнем Новгороде пройдет паблик-ток о развитии IT-сферы
23 Июня
СМИ о нас  
В Арсенале обсудят IT в Нижегородской области
16 Июня
СМИ о нас  
Обучающая программа «Веб-разработка» от HiBrain стартовала при ННГУ
15 Июня
СМИ о нас  
Оплатить ЖКХ в режиме онлайн теперь можно на портале «Карты жителя Нижегородской области»
10 Июня
СМИ о нас  
«Прекрасная идея» или напрасные затраты? IT-бизнес — о проекте редевелопмента Започаинья
10 Июня
СМИ о нас  
Нижегородские IT-компании смогут побороться за победу во всероссийском конкурсе «IT-проект: Back To The Product»
03 Июня
СМИ о нас  
Скидки и сертификаты стали доступны на «Карте жителя Нижегородской области»
01 Июня
СМИ о нас  
Фестиваль детских инновационных проектов прошел в технопарке «Кванториум Нижний Новгород»
26 Мая
СМИ о нас  
Нижегородские школьники разработали маску дополненной реальности для сервиса «Карта жителя Нижегородской области»
20 Мая
СМИ о нас  
Как интегратор 1С балуется плюшками
17 Мая
СМИ о нас  
Историческая викторина в честь 800-летия Нижнего Новгорода стартовала на “Карте жителя”
12 Мая
СМИ о нас  
Жители региона смогут получать цифровые квитанции через сервис «Карта жителя Нижегородской области
12 Мая
СМИ о нас  
Квитанции об оплате услуг ЖКХ можно получить на портале «Карта жителя»
27 Апреля
СМИ о нас  
Джентльменский набор приложений для смартфона в 2021 году
23 Апреля
СМИ о нас  
IT-компания Lad вошла в число крупнейших работодателей рынка IT в Нижнем Новгороде
16 Апреля
СМИ о нас  
Какой кошелек выбрать?
05 Апреля
СМИ о нас  
Формы платформы
04 Апреля
СМИ о нас  
На 30% Минстрой России прогнозирует повышение индекса IQ городов к 2024 году
01 Апреля
СМИ о нас  
К 2024 году в России планируется на 30% повысить индекс цифровизации городов
22 Марта
СМИ о нас  
Эко-квест «800 шагов к чистому городу»
18 Марта
СМИ о нас  
Все школы в России обеспечат доступом к интернету в этом году
06 Марта
СМИ о нас  
Команды из Нижегородской области стали победителями межрегионального онлайн-хакатона
06 Марта
СМИ о нас  
Кейс «Instagram-маски в честь 800-летия Нижнего Новгорода» от IT-компании Lad
01 Марта
СМИ о нас  
Где работать в ИТ в 2021: Lad
28 Февраля
СМИ о нас  
Нижегородский онлайн-хакатон «VRARHack52» соберет юных разработчиков со всей страны
22 Февраля
СМИ о нас  
Диагностируем проблемы в микросервисной архитектуре на Node.js с помощью OpenTracing и Jaeger
25 Декабря
СМИ о нас  
В российских школах заменяют Word и Excel на отечественные аналоги
24 Декабря
СМИ о нас  
Дмитрий Петров о налоговых льготах для IT-сферы
СМИ о нас  
Нижегородские IT-компании получат налоговые льготы
22 Декабря
СМИ о нас  
Профит для бизнеса от работы контактного центра на удаленке: кейс компании Lad
10 Декабря
СМИ о нас  
Росатом интегрирует решения российских разработчиков в проекты Smart City
07 Декабря
СМИ о нас  
Портал "Карта жителя Нижегородской области" стал удобнее
06 Декабря
СМИ о нас  
На портале «Карта жителя Нижегородской области» обновлен профиль пользователя
30 Ноября
СМИ о нас  
iCluster обсудит лучшие практики импортозамещения
27 Ноября
СМИ о нас  
Lad: цифровая трансформация бизнеса
19 Ноября
СМИ о нас  
IT-компания Lad поделится лучшими практиками
18 Ноября
СМИ о нас  
Компания Lad проведет день открытых дверей и расскажет о трендах IT-разработки
14 Ноября
СМИ о нас  
Участники регионального iCluster расскажут об отраслевых трендах
29 Октября
СМИ о нас  
О будущем проекта "Карта жителя Нижегородской области"
22 Октября
СМИ о нас  
Эксперт Lad дал комментарий Tadviser об импортозамещении офисного софта
14 Октября
СМИ о нас  
Как ИТ-специалисту устроиться на работу в хорошую компанию
07 Октября
СМИ о нас  
Карту жителя Нижегородской области начнут тестировать в октябре
06 Октября
СМИ о нас  
К сервису «Карта жителя Нижегородской области» присоединились первые банки-партнеры
01 Октября
СМИ о нас  
Пакет офисных решений "Р7-Офис" поступит в школы Ингушетии
01 Октября
СМИ о нас  
Ингушетия получит 3 тыс. лицензий на российское ПО для системы образования
25 Августа
СМИ о нас  
НБД-Банк и IT-компания Lad предлагают малому бизнесу онлайн-кассы в аренду
18 Июня
СМИ о нас  
Алтайский край переходит на российское ПО
06 Мая
СМИ о нас  
Work must go on!
03 Апреля
СМИ о нас  
IT-компании предлагают свои продукты бесплатно
26 Марта
СМИ о нас  
ПСС на Digital.Forum Construction 2020
24 Марта
СМИ о нас  
Быстрая цифровизация строительной отрасли
16 Марта
СМИ о нас  
Партнерская акция IT-компании Lad и НБД-Банка
13 Февраля
СМИ о нас  
Отечественное ПО для белгородских школьников
СМИ о нас  
Платформа HiBrain - разработка IT-компании Lad
СМИ о нас  
Digital Summit 2019
24 Октября
СМИ о нас  
В Нижнем Новгороде iCluster провёл IT-фестиваль "iFest 2019"
21 Октября
СМИ о нас  
Lad на фестивале программистов IFest
03 Октября
СМИ о нас  
Обрабатываем заказы из интернет магазина с помощью RabbitMQ и TypeScript
27 Сентября
СМИ о нас  
Lad примет участие в Digital Summit 2019
СМИ о нас  
Как IT-технологии изменили жизнь нижегородцев?
06 Августа
СМИ о нас  
В Нижегородской области запустят ПСС
07 Июня
СМИ о нас  
На ПМЭФ презентованы проекты IT-компании Lad
06 Июня
СМИ о нас  
На ПМЭФ презентованы ключевые нижегородские ИТ проекты
29 Мая
СМИ о нас  
В Нижнем Новгороде запустили цифровую платформу IT-образования HiBrain
24 Апреля
СМИ о нас  
Kari втрое ускорила оформление рассрочки
12 Февраля
СМИ о нас  
Цифровизация Retail-отрасли: актуальные тренды
23 Ноября
СМИ о нас  
Лучшие IT-проекты выбрали в Нижнем Новгороде
Поделитесь вашим мнением
Ответ успешно отправлен Мы свяжемся с вами в ближайшее время

Файлы cookies

Мы используем файлы cookies. Это необходимо для анализа трафика и корректной работы сайта. Продолжая работу с сайтом, вы подтверждаете свое согласие на применение этих технологий.

подробнее хорошо