Техническая коммуникация и документирование ПО Екатерина Степалина, SmartLabs НИУ-ВШЭ

Зачем это мне? Вы получите представление о сфере деятельности – технической коммуникации (technical communication, TC). Вы познакомитесь с современными средствами документирования (documentation tools) программных систем. Вы узнаете лучшие практики (best practices) документирования и некоторые приемы, которые могут быть полезны уже сейчас.

Техническая коммуникация Часть I

Средства коммуникации становятся все более техническими Бумажное письмо Книга … Радио и ТВ Графический пользовательский интерфейс (GUI) Интернет

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

Как пользователи, мы хотим, чтобы программы были удобными Удобство (Usability) – одна из ключевых характеристик качества в соответствии со стандартом ISO 9126.

Требуется все больше знаний в сфере технической коммуникации, чтобы скрыть сложность программы за простым интерфейсом, чтобы сделать программу и информацию о ней ПОНЯТНОЙ и ЛЕГКОДОСТУПНОЙ.

Техническая коммуникация для менеджера проекта На уровне компании - успешное выполнение проекта и обеспечение удовлетворенности пользователя На уровне проекта – управление коммуникациями в команде Для себя – развитие навыков коммуникации как Soft Skills

Кто такие технические коммуникаторы? Дизайнеры (designers) Технические писатели (technical writers) Редакторы (editors) Разработчики пользовательских интерфейсов и специалисты по эргономике (UI developers, UI usability experts) Разработчики обучающих курсов и учебных пособий (training course developers) Специалисты по информационной архитектуре (information architects) Специалистов по переводу, локализации, интернационализации пользовательских интерфейсов (translation, localization specialists) Специалисты технической поддержки (Support engineers) Специалисты по веб-маркетингу и рекламе (copy writers)

Society for Technical Communication (STC) База по программам академической подготовки в области TC Онлайн-учебные курсы Стажировки Общение и обмен опытом

Lynda.com Более 900 курсов и 57 тысяч качественных видеоуроков по инструментам и системам: – Adobe Photoshop, Illustrator, InDesign – Adobe Captivate – Corel Draw – Camtasia Studio – AutoCAD – …

Конференции Конференция Technical Communication Summit: Немецкий центр развития технической документации, электронный журнал TCWorld, конференция TC World: Австралийская конференция AODC (Online Documentation and Content Conference): Конференция Intelligent Content Блогосфера – эксперты ТК обмениваются опытом через персональные блоги:

Сделаем перерыв!

Документирование ПО Часть II

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

Виды документов

Проектные документы Техническое задание (ТЗ), или software requirements specification (SRS) План проекта Программа и методика испытаний UML-диаграммы проектируемой системы

Инструменты разработки проектной документации ДокументИнструмент (система) Техническое задание IBM Doors IBM Requisite Pro AutomatedQA Software Planner Borland Caliber RM План проекта Microsoft Project Oracle Primavera Enterprise UML-диаграммы IBM Rational Rose Altova UModel Sparx Enterprise Architect Программа и методика испытаний (Acceptance Tests Specification) Atlassian JIRA Microsoft Team Foundation System

Пользовательские документы Руководства и инструкции (User Guide, User Manual) Справки по функциям продукта (Reference) Описание изменений версии продукта (Release Notes) Ответы на вопросы (Frequently Asked Questions) Решение известных проблем (Troubleshooting) Статьи How-To Статьи о лучших практиках (Best Practices) Мультимедиа-гиды (screencasts, podcasts)

Технические документы Спецификации оборудования, систем (datasheet) Спецификации стандартов (RFC) Регламенты кодирования (coding conventions)

Документация кода Описание программных интерфейсов (API) Описание классов, их методов и свойств Описание недокументированных возможностей платформы Комментарии узких мест реализации Утилиты: JavaDoc, Doxygen

Наиболее трудоемким является процесс разработки информации (J.T. Hackos) Планирование информации (Information Planning, 10%) Проектирование (Information Design, 20%) Разработка (Information Development, 50%) Эксплуатация (Production,20%) Оценивание (Evaluation, менее 1%)

Стадии разработки документации

Что нужно для разработки документации?

Information Process Maturity Model (IPMM) Organizational structure (Организационная структура) quality assurance (Обеспечение качества) planning (Планирование) estimating (Оценка) scheduling (Составление и соблюдение графика) tracking (Отслеживание статуса задач, работ, ресурсов) hiring and training (Наем и обучение) information design (Проектирование информации) cost control (Контроль издержек) quality management (Управление качеством) collaboration (Совместная работа) JoAnn T. Hackos

Стандарты – Национальные (РФ) Российские стандарты основываются на ключевых международных стандартах: «ГОСТ Р ИСО Системы менеджмента качества» «ГОСТ Р ИСО/МЭК Информационная технология. Процессы жизненного цикла программных средств». Действующие российские стандарты: «ГОСТ Р ИСО/МЭК Информационная технология. Процесс создания документации пользователя программного средства» «ГОСТ Р ИСО/МЭК ТО Информационная технология. Руководство по управлению документированием программного обеспечения» «ГОСТ Р ИСО Системы обработки информации. Документация пользователя и информация на упаковке для потребительских программных пакетов» Устаревшие, но все еще использующиеся стандарты: GOST 19.хх - - ГОСТы серии ЕСПД (Единая система программной документации). Это стандарты х годов. Они содержат требования к оформлению руководств пользователя и программиста, схем алгоритмов, схем данных, спецификации на программный продукт. GOST 34.хх – Автоматизированные системы. Комплекс стандартов на автоматизированные системы. Самый популярный документ из этой серии - ГОСТ Техническое задание на создание автоматизированной системы. Это требования к оформлению ТЗ на АС, которые часто применяются для информационных систем, разрабатываемых для государственных организаций, учреждений и т.п.

Стандарты - Международные Международные стандарты основываются на ключевых стандартах в области разработки ПО: ISO Quality Management ISO/IEC 12207:2008. Information technologies. Software life cycle processes. ISO/IEC 15288: Systems and software engineering-System life cycle processes. Не противоречит ISO/IEC 12207:2008. Международные стандарты и рекомендации в области документирования: ISO/IEC 15289: Content of systems and software life cycle process information products (Documentation). ISO/IEC Systems and software engineering - Requirements for testers and reviewers of user documentation ISO/IEC 26514: Requirements for designers and developers of user documentation. It provides requirements for the design and development of software user documentation as part of the life cycle processes. It defines the documentation process from the viewpoint of the documentation developer.

Принцип единого источника Публикация документов в нескольких форматах (В Word, CHM) из единого источника Совместная работа группы авторов Многократное использование одних и тех же блоков контента (content re-use) Единая система индексов для всех видов выходной документации

Как это реализовано?

Информационная архитектура OASIS (Organization for Advancement of Structured Information Standards) разрабатывает и поддерживает схемы – «фреймворки» для создания информационной архитектуры. DocBook (1991, HAL Computer Systems, ORelly) DITA (2001, IBM)

DocBook Структурно-ориентированная система: раздел, подраздел, пункт, абзац Подходит для разработки некоторых видов проектных и пользовательских документов Меньшая гибкость, по сравнению с DITA

DocBook

DITA (Darwin Information Typing Architecture) Семантическая модель информационных типов Разбиение документа на «топики» по смыслу: «Task», «Question», «Workaround» Возможность добавления собственных типов, поддержка наследования Специальные средства контроля локализации Нет готовых решений, требует доработки и настройки

DITA

Системы документирования Интегрированные среды разработки документов (help authoring tools) Специальные CMS - Wiki-системы XML CMS, поддерживающие стандарт DITA

Help Authoring Tools Author-it Adobe RoboHelp MadCap Flare Help&Manual EMC Documentum Dr. Explain MindTouch

Wiki-системы MediaWiki TWiki PmWiki DokuWiki Confluence

XML CMS для работы с DITA Horizon XDocs X-Hive/Docato TEXTML Server (DITA CMS Framework) Contenta SiberSafe

Какую систему выбрать? Быстрый старт – достаточно Wiki По возрастанию стоимости внедрения: Wiki, Help authoring tools, XML CMS Wiki используют в небольших и средних компаниях. Help authoring tools применяются в средних и крупных организациях NASA, NEC, Gartner. XML CMS используется в Adobe, Boeing, Nokia, IBM, Oracle и др.

Форматы пользовательских документов Печатные документы в формате PDF, MS Word Онлайн-ресурсы (Wiki, блоги) Онлайн-справочные системы (WebHelp) Контекстные справки (HTML Help, MS Help 2, JavaHelp, FlashHelp) Электронные книги (ePub, FB2)

Стили изложения и оформления APA Style (Оформление публикаций, наглядных пособий, презентаций) IEEE Style (Для оформления стандартов IEEE) MLA Style (Оформление научных статей) ESL Standards (Подготовка публикаций для международного читателя) O'Relly Stylesheet and Word List (Оформление печатных изданий, это руководство используется издательством O'Relly, которое выпускает техническую литературу) «The Chicago Manual of Style»

Поиск…. Уделите особое внимание подбору ключевых слов.

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

А как же картинки?..

Эдварт Тафт (Edward Tufte): «Настоящее искусство – когда у наблюдателя за мгновение возникает множество идей при том, что Вы потратили всего каплю чернил на клочке бумаги».

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

Узнать больше - TC Society for Technical Communication Lynda.com Technical Writing, Id Rather Be Writing Книги и лекции Эдварда Тафта (Edward Tufte)

Узнать больше - Документирование Книги на русском языке: – Липаев В.В. Документирование сложных программных средств. – Ю.В. Кагарлицкий. Разработка документации пользователя программного продукта. Методика и стиль изложения. – В. Глаголев. Разработка технической документации. Руководство для технических писателей и локализаторов ПО. Мировые бестселлеры и мейнстрим: – The Chicago Manual of Style. – IEEE Style. (Используется для оформления научных публикаций, в частности по программной инженерии) – JoAnn T. Hackos. Information Development: Managing Your Documentation Projects, Portfolio, and People. – DITA Newsletter – Organization for the Advancement of Structured Information Standards (OASIS) – Software Engineering Process Technology (SEPT)

Спасибо за внимание! Блог:

Вопросы?