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

Технический писатель. Базовые компетенции специалиста

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

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

  • Какой цели должна служить документация?

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

    • Способствовать удобной и корректной эксплуатации программного средства.

    • Обеспечить соответствие технической документации определенному стандарту.

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

    • Предоставлять необходимую информацию для интеграции программного средства с другими программными средствами.

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

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

  • Какому стандарту должна соответствовать документация?

    Создание документации к программным средствам может регулироваться различными системами стандартов: ГОСТ, ISO, принятые корпоративные стандарты, отраслевые стандарты де-факто и т. д. Стандартом обычно определяются:

    • модель жизненного цикла программного средства;

    • состав документов, создаваемых на каждой стадии;

    • состав и структура каждого из документов.

    Тот или иной стандарт выбирается:

    • По технологическим соображениям (весь процесс разработки программного средства подчинен определенной системе стандартов).

    • По административным соображениям (заказчик или партнер-смежник требуют соблюдения той или иной системы стандартов).

    В первом случае документирование сопровождает весь процесс разработки программного средства.

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

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

  • Кто является потенциальным читателем документации?

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

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

  • Какие требования качества предъявляются к документации?

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

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

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

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

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

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

  • Кому поручается непосредственное выполнение работы?

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

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

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

    • Специально выделенный для этого член команды разработчиков — технический писатель.

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

    • Сотрудник или сотрудники отдела технической документации.

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

    • Внешний исполнитель.

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

  • Как распределяются основные обязанности?

    Основные обязанности распределяются следующим образом:

    • Исполнитель. Технический писатель или группа технических писателей.

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

    • Тестировщик. Один или несколько сотрудников, которые проверяют техническую документацию на предмет ее соответствия программному средству.

    • Редактор. Сотрудник, занятый проверкой технической документации с точки зрения соблюдения принятых стандартов и критериев качества.

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

    • Корректор.

    • Ответственный приемщик. Должностное лицо в корпорации, принимающее решение о готовности документации и ее соответствии требованиям.

    Взаимодействие между этими инстанциями планируется заранее и может существенным образом варьироваться.

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

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

  • Как работа над технической документацией привязана к жизненному циклу программного средства?

    Работа над технической документацией может выполняться:

    • На тех или иных стадиях жизненного цикла.

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

    • На стадии внедрения или сопровождения.

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

  • Как работа над технической документацией организована во времени?

    Работа над технической документацией может организована во времени двумя способами:

    • Срочная работа.

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

      Внешний исполнитель в этом случае привлекается к работе на основе срочного заказа.

    • Постоянное сопровождение.

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

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

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

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

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

  • Microsoft Word – PDF

    Текст пишется с использованием текстового редактора Microsoft Word (в составе Microsoft Office) и затем конвертируется в формат PDF. Технологическая цепочка позволяет готовить бумажные публикации (а также комплекты электронной документации в формате PDF).

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

  • Adobe FrameMaker – PDF

    Текст верстается с использованием программного комплекса Adobe FrameMaker и затем конвертируется в формат PDF. Технологическая цепочка позволяет готовить бумажные публикации (а также комплекты электронной документации в формате PDF). Возможно также преобразование в другие форматы (RTF, HTML, различные приложения XML и т. д.).

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

  • Технологии подготовки контекстной справки

    Технологические цепочки этого типа используются для создания контекстной справки в одном из распространенных форматов: WinHelp, HTML Help и т. д. Цепочка может включать в себя специализированную программную систему (ForeHelp, eHelp RoboHelp) или обходиться без нее.

    Технологии подготовки контекстной справки требуют затрат на внедрение и согласование действий между техническим писателем и командой разработчиков.

  • Технология единого источника на основе DocBook

    Текст технической документации изначально пишется на языке разметки DocBook и используется в качестве единого источника. Две параллельные технологические цепочки позволяют получить файл в формате PDF (который в дальнейшем распространяется в электронном виде или служит основой для бумажной публикации) или файл в формате HTML Help.

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

    Технология нуждается в значительных затратах усилий на внедрение.

    Внедрение той или иной технологической цепочки осуществляется в несколько этапов:

    • Техническая экспертиза задачи.

    • Выбор технологической цепочки.

    • Установка необходимого программного обеспечения и оборудования.

    • Наладка программного обеспечения и оборудование, а также обучение персонала.

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

    • Тестирование.

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

Разработка технической документации к программному средству состоит из следующих этапов.

  • Сбор информации о программном средстве.

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

    • Реализованная или предполагаемая к реализации функциональность программного средства.

    • Структура пользовательского интерфейса.

    • Практические задачи, решаемые при эксплуатации программного средства.

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

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

  • Составление структуры документации.

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

  • Написание текста.

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

  • Изготовление иллюстраций.

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

  • Создание аппарата документа.

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

    • Перекрестные ссылки

    • Оглавление

    • Список иллюстраций

    • Список таблиц

    • Указатель

    • Глоссарий

    Системы контекстной справки снабжаются аппаратом, который предусмотрен избранным форматом справки. Например, справка в формате HTML Help имеет оглавление, указатель, гиперссылки из одного раздела в другой, ссылки типа «См. также» и т. п.

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

  • Сборка документа или комплекта документации.

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

    • Соединение частей документации воедино.

    • Формирование единого аппарата документации.

    • Выявление терминологических расхождений и их устранение.

  • Литературное редактирование.

    Литературное редактирование выполняется в тех случаях, когда к стилю документации предъявляются достаточно высокие требования. Литературное редактирование включает в себя следующие аспекты:

    • Устранение стилистических недочетов.

    • Приведение текста в соответствие со специальными требованиями заказчика.

    • Устранение случайных терминологических недочетов (нарушения единства терминологии, неправильное употребление терминов и т. д.).

  • Верстка.

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

    • Сравнительно несложная верстка в Microsoft Word.

      Выполняется самим техническим писателем или верстальщиком с использованием специально разработанных шаблонов.

    • Профессиональная верстка в издательских системах (чаще всего в Adobe FrameMaker).

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

    • Верстка в технологии единого источника на основе DocBook.

      При формировании PDF-файла осуществляется автоматически на основе заданного шаблона.

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

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

  • Оформление по ГОСТ или другому стандарту.

    В случае если к оформлению документации предъявляются специализированные требования какого-либо стандарта (например, ГОСТ), выполняется определенная работа по переоформлению готовых документов. Переоформление фактически выполняется в рамках процесса верстки. Стандартное оформление документации облегчается за счет заготовленных заранее шаблонов и заготовленных образцов.

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

  • Корректорская правка.

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

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

  • Изготовление электронного документа в формате PDF.

    Электронный документ первоначально создается с использованием одного из упомянутых выше инструментов. Различают WYSIWYG-инструменты (Microsoft Word, Adobe FrameMaker) и инструменты, позволяющие строго разграничить форму и содержание (технологии, основанные на DocBook).

    • Для WYSIWYG-инструментов окончательный вид документа может быть получен уже на стадии разработки документа. Однако по целому ряду причин рабочий формат неудобен для распространения. Поэтому выполняется преобразование в другой формат, как правило в формат PDF. Поэтому выполняется преобразование в другой формат, как правило в формат PDF.

      Формат PDF позволяет хранить документ в виде одного файла, для просмотра которого необходима лишь свободно распространяемая программа Acrobat Reader. При этом вид документа остается одним и тем же, независимо от настроек компьютера и операционной системы.

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

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

    • Для технологии единого источника на основе DocBook окончательный вид документа получается только после преобразования в тот или иной формат — в данном случае в формат PDF. Результатом разработки является определенным образом структурированное содержимое документации — единый источник. Только в результате производства появляются документы как таковые с присущими им свойствами: титульный лист, определенная последовательность изложения, те или иные элементы оформления, аппарат и т. д.

      Составом комплекта документации, составом и внешним видом отдельных документов управляют с помощью различных шаблонов и других настроек процесса преобразования DocBook — PDF.

  • Изготовление печатной публикации.

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

    • Преобразование подготовленного ранее макета в формат PDF.

    • Размещение заказа в типографии.

    • Передача в типографию материалов.

    • Получение тиража.

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

    Разные типографии принимают исходные материалы в разной форме. Некоторые из них готовы работать с макетом в рабочем формате (Microsoft Word, Adobe FrameMaker). Другие предъявляют более жесткие требования. Оптимальным является порядок, при котором в типографию передается файл или файлы в формате PDF, в которых содержится готовый оригинал-макет будущей публикации. Типография берет на себя изготовление пленок, печать и переплетные работы.

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

  • Компиляция справочной системы.

    Работа по подготовке системы контекстной справки организуется в виде цикла, который включает постоянную работу по подготовке и обновлению текста и периодическую компиляцию итоговых файлов (в формате WinHelp, HTML Help и т. п.). Какие бы средства не использовались для подготовки текста справки: специализированные WYSIWYG-инструменты, произвольные HTML- или RTF-редакторы, технология единого источника на основе DocBook или какие-то иные технологии, — производство итоговых файлов выполняется посредством запуска стандартного компилятора справки выбранного формата.

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

+7 (499) 500-44-77

mail@philosoft.ru

SpyLOG