Документирование

Документирование — запись информации на различных носителях по установ­ленным правилам (ГОСТ Р 51141-98 Делопроизводство и архивное дело. Термины и определения).

Правовой аспект докуметирования в РФ устанавливает Статья 11 Федерального закона от 27.07.2006 № 149-ФЗ.

Стандарты

  • ISO/IEC/IEEE 1528 описывает универсальные типы информационных документов и конкретных типов документации, используемых на протяжении жизненного цикла информационных систем и программного обеспечения, требования к их содержанию, указывает соответствия этих типов документации и информационных продуктов, описанных в стандартах жизненного цикла информационных систем, стандартах жизненного цикла программных продуктов, стандартах на процессы управления услугами.
  • ISO 9000 содержит требования к документированию бизнес-процессов предприятия.
  • РД 50-34.698-90 содержит требования к содержанию документов на автоматизированную систему по ГОСТ 34.
  • ЕСПД (ГОСТ 19) устанавливает правила разработки, оформления и обращения программ и программной документации.
  • ЕСКД устанавливает правила, требования и нормы по разработке, оформлению и обращению конструкторской документации.
  • IEEE 1063-2001 содержит минимальные требования к структуре, содержанию и формату пользовательской документации для программных систем.
  • ГОСТ Р 51904-2002 устанавливает общие требования к разработке и документированию программного обеспечения встроенных систем реального времени.
  • ISO/IEC 15910 описывает процесс создания документации пользователя программного средства.

Процесс документирования по ISO/IEC 12207

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

Данный процесс состоит из следующих работ:

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

Дисциплины

Техническое писательство (technical writing) — составление и редактура технических документов.

Техническое писательство возникло и развивается в двух направлениях:

  • От исполнителя (разработчика, производителя) к заказчику (пользователю, потребителю). Суть этого направления - изучение продукта (оборудования, программы) и написание понятных для пользования руководств, инструкций, памяток, подготовка презентаций, буклетов и т.д. В этом случае техписатель выступает в качестве переводчика со специального профессионального русского языка или профессионального сленга на общедоступный русский язык.
  • От заказчика к исполнителю. В этом случае технический писатель выступает в роли аналитика, маркетолога. Он выявляет потребность клиента и формализует ее в качестве задачи исполнителю. Задача излагается в соответствующих отрасли терминах в форме заказа или технического задания.
Techwriting.jpg

Инструменты

Можно выделить несколько групп программного обеспечения, используемого для документирования:

  1. Текстовые процессоры (Word processors) — компьютерная программа, используемая для написания и модификации документов, компоновки макета текста и предварительного просмотра документов в том виде, в котором они будут напечатаны (свойство, известное как WYSIWYG)
    • Scrivener
    • Microsoft Word
    • Apple Pages
    • LibreOffice Writer
  2. Настольные издательские системы (Desktop publishing tools) — программное обеспечение для подготовки оригинал-макета издания, готового для передачи в типографию. Выполняют те же функции, что и текстовые процессоры, а также дают дополнительные возможности для оформления документов, такие как автоматизация форматирования.
    • С графическим интерфейсом
      • Adobe FrameMaker
      • Adobe InDesign
      • Adobe PageMaker
      • Apple Pages
      • Microsoft Office Publisher
      • QuarkXPress
      • Scribus
      • Xara Page & Layout Designer
    • С текстовым интерфейсом
      • Corel Ventura
      • TeX (LaTeX, XeTeX)
  3. Системы для разработки технической документации (Help authoring tools, HAT) — программное обеспечение, используемое техническими писателями для создания сопроводительной документации к программным продуктам. Документация публикуется в виде файла в скомпилированном (WinHelp (*.HLP) или Microsoft Compiled HTML Help (*.CHM)) или нескомпилированном (PDF, XML, HTML или JavaHelp) форматах. Такие системы могут включать в себя следующие возможности: генерация книжного указателя, проверка правописания, автоматизированный перевод, принцип единого источника.
    • Adobe RoboHelp
    • AsciiDoc
    • ClickHelp
    • Help & Manual
    • Help Generator
    • HelpNDoc
    • MadCap Flare
    • Sandcastle
  4. Программное обеспечение совместной работы (Collaborative software) — используется для поддержки взаимодействия между стейкхолдерами и членами команды, при совместной работе над документацией.
    • Wiki-системы
      • MediaWiki
      • eXo Platform
      • Atlassian Confluence
    • Платформы для совместной работы (shared document workspaces)
      • Microsoft SharePoint
      • Google Docs
Источник — «http://sewiki.ru/index.php?title=Документирование&oldid=3349»