Клуб технических писателей

Работа над документом. Часть 1. Сбор сведений

Маргарита
15 апреля 2015, 16:05
Процесс создания документа включает в себя такие этапы, как:
— сбор сведений;
— анализ;
— разработка;
— рецензирование.
В этой статье я расскажу о первом этапе — сборе сведений. Поясню, почему он важен, какую информацию необходимо получить и кто может помочь в этом.

Главное назначение документа — помогать читателю решать необходимые ему задачи. Поэтому, прежде всего, необходимо выяснить:
  1. Целевую аудиторию.
  2. Задачи целевой аудитории.
Также нужно извлечь у заказчика все возможные ресурсы для работы над документом.

Целевая аудитория
Чтобы документ был полезным и востребованным, нужно учитывать потребности и способности его читателей.
Потребности читателей позволяют понять какие особенности и качества объекта необходимо описывать, то есть определяют содержание документа. Например, описанием программного продукта может являться:
— описание его преимуществ и возможностей с целью знакомства и продвижения (для менеджеров проектов);
— инструкцией по использованию (для пользователей продуктом);
— справочником структурных элементов кода (для программистов, поддерживающих работоспособность продукта) и др.
Способности читателя помогают определиться со степенью детализации и контекстом описания. Например, читателями инструкции по заполнению таблиц расписаний могут быть как диспетчер автостанции поселка, так и администратор транспортного сайта. Знание целевой аудитории поможет понять, насколько подробно нужно освещать тот или иной аспект, и значительно сужает круг анализируемой в дальнейшем информации.

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

Ресурсы для работы
Это источники информации для самостоятельного анализа, тестирования и изучения объекта описания. А именно:
  1. Существующее описание объекта (текстовые заметки, аудио- и видео-записи).
  2. Сам объект описания (интерфейс и доступ к нему или исходники программного продукта и среда для его отладки).
  3. Координаты коллег, которые могут помочь с информацией по объекту описания.

Все эти сведения можно получить только в диалоге с заказчиком — только он  знает, какие проблемы хочет решить. После обсуждения с заказчиком необходимо провести самостоятельный анализ. Например, поставить себя на место читателя и обдумать его желания. Возникшие идеи нужно обязательно согласовать.
Диалог можно организовать в виде личной встречи, письменно или по телефону. К переговорам следует подготовиться — составить список нужных вопросов, настроиться на дружелюбную и продуктивную беседу. 
В ходе диалога важно задавать только нужные на данный момент вопросы. Если заказчик углубляется в детали, нужно вежливо направить его в нужную сторону. Также очень важна эмоциональная составляющая. Предже чем начинать говорить о делах, полезно подружиться с заказчиком, например, поговорить о приятной погоде или рассказать короткую смешную историю про себя. От этого зависит эффективность вашей совместной работы в дальнейшем.

Заключение
Если вам удалось выяснить цели документа и получить все необходимые средства для дальнейшей работы, можно приступать ко второму этапу — анализу. О нем речь пойдет в следующей моей статье.
14 комментариев
Подписаться на комментарии к посту

Спасибо!

Казалось бы, очевидные вещи. Но прекрасно изложены и структурированы.

По поводу разговоров о погоде и прочих "предварительных ласках" не совсем согласна. Если заказчик ограничен во времени, а так оно обычно и бывает, то отвлеченные разговоры в начале беседы могут вызвать раздражение.

 

Маргарита
16 апреля 2015, 15:18

Тогда просто улыбнуться :), это раздражения точно не вызовет. 

Я бы сказала - настроиться на собеседника. Если он к смешочкам не склонен, а серьезен и суров, лучше принять деловой тон.

Маргарита
17 апреля 2015, 17:10

Говоря о "дружбе" с заказчиком в статье,  я хотела сказать как можно снять именно эту суровость :). А дела решать конечно же только в деловом тоне. 

Действительно, важно не переборщить.

Виктор Фигурнов
19 апреля 2015, 23:38

Очень интересный текст, спасибо.

Три замечания.

1. Далеко не всегда "главное назначение документа — помогать читателю решать необходимые ему задачи". Например, назначение анкеты — собрать информацию, нужную составителю анкеты, а не читателю. Назначение договора — зафиксировать права и обязанности сторон по поводу предмета довогора.И т. д.

2. Сбор и анализ сведений — не два этапа, а один. Нельзя сначала собрать сведения, а потом проанализировать. Обычно сначала собираются какие-то данные, анализируются, по результатам анализа выявляется, каких сведений не хватает, и т.д.

3. Работа над документом не начинается со сбора сведений. И не заканчивается рецензированием. "За бортом" осталось множество важных этапов.

Маргарита
20 апреля 2015, 09:58

Виктор, спасибо за интерес к статье!

1. В статье я рассматриваю документ как источник информации для специалистов в сфере IT, а не в правовой или организационной.

2. Конечно, многие этапы тесно связаны и  выполняются в итеративном порядке. Но начинать анализировать что-нибудь на всякий случай непродуктивно. На первой встрече необходимо узнать что анализировать, где и с помощью чего.

А позже анализировать и конечно же дальше собирать... Потом опять анализировать и ... т. д.

3. Виктор, с чего у Вас начинается работа над документом? И почему? Очень интересно. 


 

Виктор Фигурнов
20 апреля 2015, 20:39

Маргарита, спасибо за интересные вопросы. Отвечаю.

В статье я рассматриваю документ как источник информации для специалистов в сфере IT, а не в правовой или организационной.

1. В своей статье вы написали про "документ", не оговорив область его применения и прочие характеристики.

2. Договор (например, лицензионное соглашение, сервисное соглашение), и анкета (например, анкета для пользователей программного продукта) могут быть важными источниками информации для специалистов в сфере IT. В стандарте ISO 15289:2011 о документации жизненного цикла систем и программного обеспечения описываются такие виды документов как Contract (п. 10.18) и Customer Satisfaction Survey (п. 10.19). 

начинать анализировать что-нибудь на всякий случай непродуктивно. На первой встрече необходимо узнать что анализировать, где и с помощью чего.

Могут быть разные ситуации. Например, вам могут еще до "первой встречи" прислать несколько десятков, или сотен, или тысяч страниц, которые надо прочесть и проанализировать, чтобы на первой встрече вести предметный разговор.

Или вы можете уже иметь все необходимые сведения, быть в курсе дела. Тогда вам надо проанализировать эти сведения применительно к новой задаче.

Кроме того, "сбор сведений" - это не обязательно интервью с заказчиком, разработчиком, экспертом, и т.п. Иногда вам надо поработать с той системой, которую будете описывать, чтобы получить о ней представление, приобрести некоторый опыт, решить какие-то задачи, набить шишки и т.п. И уже потом общаться с заказчиком, разработчиком, экспертом...  

с чего у Вас начинается работа над документом?

Если документ регламентированный, т.е. его создание обязательно по договору, регламенту, закону и т.п., то с запуска проекта создания документа или набора документов.

Если документ нерегламентированный - с идеи о создании такого документа.

Маргарита
21 апреля 2015, 10:06

Виктор, очень интересны ваши сведения, спасибо.

 

Далеко не всегда "главное назначение документа — помогать читателю решать необходимые ему задачи"

 

Анкета, составленная правильно, помогает читателю быстро ее заполнить. Здесь нужно тоже ориентироваться под нужды читателя. Иначе возникнет много вопросов. Это же касается и соглашения.

В статье "назначение" я упомянула в ракурсе разработки документа. Понятно, что у любого документа есть конечная цель, например, пиар продукта и сбор денег с конечных пользователей, фиксация соглашений и др. 

 

Маргарита
21 апреля 2015, 10:10
Могут быть разные ситуации. Например, вам могут еще до "первой встречи" прислать несколько десятков, или сотен, или тысяч страниц, которые надо прочесть ипроанализировать..


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

Маргарита
20 апреля 2015, 10:08

В моей статье, каждый этап описывает оределенный тип работ и не является строго последовательным в очереди дел над документом.

После рецензирования следует этап доработки документа. 

Какие работы Вы выполняете после рецензирования?

Спасибо.

Виктор Фигурнов
20 апреля 2015, 21:18

Зависит от вида документа. Могут быть такие работы.

Доработка.

Тестирование, контроль качества.

Конечная сборка/верстка и т.п.

Утверждение/одобрение.

Публикация/тиражирование/доставка

Управление версиями, локализациями и адаптациями

Обновление и поддержка.

Маргарита
21 апреля 2015, 10:17
Вы правильно заметили.  Я перечислила только те, которые касаются разработки и проверки. Я планирую рассказать в клубе только о них.

Маргарита, скажите, почему вы решили удалить мой комментарий? Я тезисно напомню, о чём он был:

1) Статья написана канцеляритом, хотя команда техписателей Яндекса постоянно призывает с ним бороться.

2) Стаья написана с грамматическими и речевыми ошибками.

3) Часть советов в статье как минимум спорны.

Комментарий был удален по причине несоответствия нормам этики и деловой переписки. Надеемся на сознательность и умеренность в дальнейшем.