КомпанияУслугиОбучениеСервисы

Отчет о семинаре «Документирование сегодня», фев. 2008 г.

Версия для печати

Событие

Семинар «Документирование сегодня» состоялся 20 февраля 2008 г. в Москве по адресу Трехпрудный переулок д. 9. Мероприятие подготовлено и проведено компанией PhiloSoft Technical Communications (http://www.philosoft.ru).

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

На семинаре Ю. В. Кагарлицкий и М. Ю. Острогорский выступили с докладом «Документирование сегодня», после чего ответили на вопросы слушателей.

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

Участие в семинаре было бесплатным.

Аудитория

Семинар собрал 38 участников: технических писателей, руководителей отделов документирования, системных аналитиков. Примечательно, что на семинаре присутствовали не только москвичи, но и гости их других городов: Коломны, Нижнего Новгорода, Санкт-Петербурга, Ульяновска.

Тезисы доклада

1. В каких условиях работают сегодня технические писатели?

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

  • разработка оборудования и программных продуктов;
  • разработка заказных систем;
  • обслуживание корпоративных ИТ-инфраструктур.

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

2. Что объединяет всех технических писателей?

Деятельность технического писателя может быть универсальным образом выражена через его функцию (можно даже сказать, миссию) в обществе. Вне зависимости от особенностей ситуации технический писатель всегда решает коммуникационную задачу, возникающую вокруг определенного технического решения. Она состоит в том, чтобы предоставить лицам, заинтересованным тем или иным образом в этом техническом решении, необходимую им информацию в приемлемой для них форме. Иными словами, технический писатель формирует коммуникационный канал: собирает информацию о техническом решении, систематизирует ее, а затем сообщает одной или нескольким целевым аудиториям. Важно, что этот канал должен быть отчуждаемым, поскольку технический писатель (в отличие, допустим, от специалиста-наставника или преподавателя на курсах) не в состоянии объясняться с каждым адресатом лично. Требование отчуждаемости делает задачу технического писателя в особенности нетривиальной и во многом определяет методы и средства ее решения.

3. Каково содержание работы технического писателя?

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

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

Анализ целевых аудиторий составляет инженерную, творческую часть проектирования комплекта документации. С другой стороны, формальной основой проектирования комплекта служат:

  • структура технического решения, задающая предметы описания;
  • стандарты, задающие аспекты описания.

(В одних стандартах аспекты описания даны буквально как конкретные типы документов с определенным составом и содержанием, а в других в более общей форме как темы, которые обязательно должны быть освещены.)

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

Некоторые современные стандарты ИСО/МЭК (в частности, ISO/IEC 18019) предлагают методики проектирования комплекта документации на основании анализа целевых аудиторий.

Формирование документа. Если само включение документа в состав комплекта документации определяется профилированием информации по целевой аудитории, то внутренняя структура документа зависит, прежде всего, от преимущественного способа его использования предполагаемым адресатом. Основных способа два: систематическое чтение (“manual mode”) и чтение от случая к случаю для получения справки (“reference mode”).

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

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

Методика изложения связана с выбором предметов описания не на уровне документа в целом, а на уровне его разделов и подразделов. Например, описывая программу, мы можем концентрироваться на ее функциях (что она «умеет»), а можем на пользовательских задачах (чего пользователь стремится с ее помощью достичь). Методику изложения материала технический писатель выбирает, руководствуясь содержательными соображениями.

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

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

Повтор фрагментов текста и структуры. Все документы типа «руководство пользователя» имеют сходную структуру. Назначение каждого модуля приводится и в руководстве пользователя на него, и в общем описании программного комплекса. Все модули имеют унифицированный интерфейс, но его описание приводится в руководстве пользователя на каждый модуль (а не выносится в отдельный документ). Тексты справочных файлов во многом повторяют тексты руководств пользователя.

Автоматизация документирования. Основу автоматизации документирования сегодня образует т.н. принцип единого источника, который в самом общем виде предполагает:

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

Образно говоря, содержание документа последовательно «обзаводится» сначала составом и структурой, затем оформлением, и, наконец, электронным представлением.

Принцип единого источника

Инструментарий. В настоящее время техническому писателю доступно много разных инструментов, в той или иной степени реализующих принцип единого источника. Их можно разделить на три основных группы:

  • средства, основанные на редакторах документов (Microsoft Word, Adobe FrameMaker);
  • средства, основанные на языках разметки (DITA, DocBook, TeX);
  • интегрированные среды (AuthorIT, Help & Manual, RoboHELP, SiberSafe).

Четвертую группу составляют разнородные оригинальные решения, в том числе, не предназначенные для документирования как такового, но пригодные для решения таких задач, например, комбинация системы управления требованиями Rational RequisitePro и генератор отчетов SoDA.

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

Унификация языка и стиля изложения. Принцип единого источника подразумевает, что автоматически сформированные документы не подлежат последующей обработке вручную, в противном случае эффективность такой технологии резко снижается. Вместе с тем, недопустимо, чтобы документ представлял собой «лоскутное одеяло», состоящее фрагментов, написанных по-разному. Поэтому автоматизация документирования предъявляет повышенные требования к унификации стиля изложения документации. В частности, должны быть унифицированы следующие черты стиля:

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

Мерами по унификации стиля в авторских коллективах могут служить:

  • глоссарии;
  • периодические совещания для авторов;
  • руководства по стилю.
    Кроме того, частично описания могут быть унифицированы техническими средствами. Некоторые решения, в том числе, DITA, предоставляют для этого определенные механизмы.

4. Что технический писатель должен уметь в первую очередь?

Квалификация современного технического писателя базируется на следующих восьми основных умениях:

  • i) собирать и систематизировать информацию о техническом решении;
  • ii) проектировать комплект документации;
  • iii) разрабатывать структуру документа;
  • iv) унифицировать стиль изложения и придерживаться выбранного стиля;
  • v) унифицировать оформление документов и соответственно оформлять документы;
  • vi) выбирать и применять форматы электронных документов;
  • vii) выбирать и применять средства разработки документации;
  • viii) планировать собственную работу.

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

Восемь «доблестей» технического писателя

5. На что технические писатели могут претендовать?

Сверхзадача технического писателя — формирование полноценной среды технической коммуникации на предприятии. Такая среда обладает следующими свойствами:

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

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

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

В настоящее время столь масштабных задач перед техническими писателями обычно не ставят. Вместе с тем, располагая необходимыми инструментами и методами, технические писатели вполне могли бы претендовать на такую работу, а также на соответствующие ее уровню статус и оплату. Однако для этого они должны сами систематически формулировать подобные предложения, «продавать» эту идею своим работодателям и заказчикам.

Вопросы после доклада

В: Какие средства разработки документации лучше всего подходят для использования в России?

О: Все более-менее развитые инструменты нам подходят. Средства разработки вообще очень мобильны, потому что их технически легко заимствовать: приобрел (тем или иным способом), установил, научился работать. Известны и описаны успешные примеры адаптации зарубежных средств разработки к такому элементу местного колорита, как советские госты серии 2, 19 и 34.

Некоторое время назад одним из самых труднопреодолимых препятствий на этом пути было отсутствие полноценной поддержки русского языка (хотя бы на уровне поддержки кириллицы, не говоря о корректном поиске и т.п.). Многие фирмы-разработчики как будто принципиально не хотели учитывать, что есть такая страна, Россия. Но по мере общей интернационализации базовых технологий эта проблема уходит в прошлое сама собой.

В: Чем отличаются западные технические писатели от российских?

О: Во-первых, образованием. В США, в Канаде, во многих странах Европы технический писатель или technical communicator официально признанная профессия и специальность. Можно учиться на технического писателя четыре года или шесть лет, получив степень бакалавра или магистра соответственно. Интересно, что некоторые университеты трактуют эту специальность как гуманитарную, а некоторые как техническую, однако, программы в обоих случаях очень похожи.

Во-вторых, зарплаты наших технических писателей все еще отстают от зарплат зарубежных коллег. Речь в данном случае не об абсолютных суммах (такое сравнение не было бы корректным из-за множества различий в структуре расходов человека «у нас» и «у них»), а об отношении зарплаты технического писателя к зарплате, скажем, программиста. Мы по этому показателю отстаем процентов на 30.

В-третьих, у нас технический писатель существует почти исключительно в сфере информационных технологий (включая ИТ-департаменты компаний любого профиля). Зарубежные специалисты по технической коммуникации работают в разных отраслях.

В: Какова роль технического писателя при подготовке такой документации, как технические задания и технические проекты?

О: Технический писатель не может заменить собой аналитика или проектировщика, во всяком случае, если речь не идет о профанации их работы, создании бумажной «потемкинской деревни» для заказчика. Но он может взять на себя большой объем работы по редактированию материала, который предоставляют аналитики и проектировщики, и оформлению этого материала в виде документов, удовлетворяющих используемым стандартам. Строго говоря, написанием документов должны были бы сами аналитики и проектировщики, но эти специалисты не всегда достаточно хорошо пишут, и очень часто не располагают необходимым для этого временем из-за постоянных перегрузок. Также силами технических писателей может быть налажен единый источник для автоматизированного формирования проектной документации.

В: Как выбрать правильную терминологию при написании документации?

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

Анонимный опрос участников семинара

Опрос проводился путем анкетирования. Каждому участнику семинара был выдан бланк для заполнения. На предложение приять участие в анонимном опросе откликнулись 36 участников, в том числе, 31 технический писатель.

Анонимный опрос дал следующие результаты.

Нравится ли вам ваша работа?
определенно нравится 90% (28 из 31)
отношусь равнодушно 6% (2 из 31)
Как вы стали техническим писателем?
это был мой сознательный выбор 55% (17 из 31)
случайно (предложили, попробовал, получилось) 42% (13 из 31)
другие варианты 3% (1 из 31)
Каковы ваши ближайшие планы в смысле карьеры?
расти профессионально 87% (27 из 31)
стать начальником отдела 13% (4 из 31)
сменить профессию 6% (2 из 31)
другие планы 10% (3 из 31)
На каком языке вы пишете?
на русском 100% (31 из 31)
на английском 25% (8 из 32)
Какой инструментарий вы используете?
(Word как повсеместно используемый продукт в опросе не фигурировал.)
AuthorIT 10% (3 из 31)
Help & Manual 19% (6 из 31)
RoboHELP 13% (4 из 31)
DocBook 10% (3 из 31)
DITA 13% (4 из 31)
TeX 3% (1 из 31)
FrameMaker 3% (1 из 31)
OpenOffice 3% (1 из 31)
Где и в каком режиме вы работаете?
в офисе по строгому графику 70% (22 из 31)
в офисе по свободному графику 25% (8 из 31)
дома, прихожу в офис по мере необходимости 3% (1 из 31)
Какая у вас зарплата («чистыми» на руки)?
минимум по анкетам 20 тыс. руб.
максимум по анкетам 45 тыс. руб.
Выполняете ли вы работу в частном порядке?
да, систематически 19% (6 из 31)
да, эпизодически 35% (11 из 31)
нет, мне не предлагают 25% (8 из 31)
нет, принципиально 16% (5 из 31)

© «Философт», 2008–2017

+7 (499) 500-44-77

mail@philosoft.ru

SpyLOG