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

Техническая коммуникация и
документирование ПО
Екатерина Степалина, 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:
www.summit.stc.org
Немецкий центр развития
технической документации,
электронный журнал TCWorld,
конференция TC World:
www.tekom.de
Австралийская конференция AODC
(Online Documentation and Content
Conference): www.aodc.com.au
Конференция Intelligent Content
www.rockley.com/IC2011
Блогосфера – эксперты ТК
обмениваются опытом через
персональные блоги:
www.mashstream.com,
www.idratherbewriting.com
Сделаем перерыв!
Часть 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

Sparx Enterprise Architect

Altova UModel

Microsoft Team Foundation
System
Программа и

методика испытаний
(Acceptance Tests
Specification)
Atlassian JIRA
Пользовательские документы
• Руководства и инструкции (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)
JoAnn T. Hackos
• Organizational structure (Организационная
структура)
• quality assurance (Обеспечение качества)
• planning (Планирование)
• estimating (Оценка)
• scheduling (Составление и соблюдение
графика)
• tracking (Отслеживание статуса задач, работ,
ресурсов)
• hiring and training (Наем и обучение)
• information design (Проектирование
информации)
• cost control (Контроль издержек)
• quality management (Управление качеством)
• collaboration (Совместная работа)
Стандарты – Национальные (РФ)
Российские стандарты основываются на ключевых международных стандартах:
• «ГОСТ Р ИСО 9001-2008. Системы менеджмента качества»
• «ГОСТ Р ИСО/МЭК 12207-99. Информационная технология. Процессы жизненного цикла
программных средств»
.
Действующие российские стандарты:
«ГОСТ Р ИСО/МЭК 15910-2002. Информационная технология. Процесс создания документации
пользователя программного средства»
«ГОСТ Р ИСО/МЭК ТО 9294-93. Информационная технология. Руководство по управлению
документированием программного обеспечения»
«ГОСТ Р ИСО 9127-94. Системы обработки информации. Документация пользователя и
информация на упаковке для потребительских программных пакетов»
Устаревшие, но все еще использующиеся стандарты:
• GOST 19.хх - - ГОСТы серии ЕСПД (Единая система программной документации). Это
стандарты 80-90-х годов. Они содержат требования к оформлению руководств пользователя и
программиста, схем алгоритмов, схем данных, спецификации на программный продукт.
• GOST 34.хх – Автоматизированные системы. Комплекс стандартов на автоматизированные
системы.
Самый популярный документ из этой серии - ГОСТ 34.602-89 Техническое задание на
создание автоматизированной системы. Это требования к оформлению ТЗ на АС, которые
часто применяются для информационных систем, разрабатываемых для государственных
организаций, учреждений и т.п.
Стандарты - Международные
Международные стандарты основываются на ключевых стандартах
в области разработки ПО:
• ISO 9000. Quality Management
• ISO/IEC 12207:2008. Information technologies. Software life cycle
processes.
• ISO/IEC 15288:2008 - Systems and software engineering-System life cycle
processes. Не противоречит ISO/IEC 12207:2008.
Международные стандарты и рекомендации в области
документирования:
• ISO/IEC 15289:2006 - Content of systems and software life cycle process
information products (Documentation).
• ISO/IEC 26513 - Systems and software engineering - Requirements for
testers and reviewers of user documentation
• ISO/IEC 26514:2008 - 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,
O’Relly)
• 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, которое
выпускает техническую литературу)
Поиск….
Уделите особое
внимание
подбору
ключевых слов.
Как отличить хорошую
документацию от плохой?
• Ориентируйтесь на задачи, которые хочет
выполнить пользователь, а не на «фичи» продукта.
• Ориентируйтесь на конкретный класс
пользователей.
• Используйте словарь терминов – глоссарий.
• Включайте только ту информацию, которая
действительно нужна пользователю.
• Побуждайте пользователя изучать возможности
системы через ее интерфейс.
• Используйте текст повторно для снижения
трудозатрат на разработку документации.
А как же картинки?..
Эдварт Тафт (Edward Tufte): «Настоящее
искусство – когда у наблюдателя за мгновение
возникает множество идей при том, что Вы
потратили всего каплю чернил на клочке
бумаги».
Заключение
• Техническая коммуникация (TC) – актуальная и
активно развивающаяся область знаний,
объединяющая представителей различных
профессий – от дизайнера и технического писателя
до специалиста по информационной архитектуре и
разработчика пользовательского интерфейса.
• Документирование – один из важных разделов TC,
который охватывает информационную поддержку и
сопровождение продукта, требует тщательной
разработки информационной архитектуры и
правильного выбора инструментов.
Узнать больше - TC
• Society for Technical Communication
www.stc.org
• Lynda.com www.lynda.com
• Technical Writing, I’d Rather Be Writing
www.idratherbewriting.com
• Книги и лекции Эдварда Тафта (Edward
Tufte) www.edwardtufte.com
Узнать больше - Документирование
• Книги на русском языке:
– Липаев В.В. Документирование сложных программных средств.
– Ю.В. Кагарлицкий. Разработка документации пользователя
программного продукта. Методика и стиль изложения.
– В. Глаголев. Разработка технической документации. Руководство
для технических писателей и локализаторов ПО.
• Мировые бестселлеры и мейнстрим:
– The Chicago Manual of Style.
– IEEE Style. www.standards.ieee.org/guides/style (Используется для
оформления научных публикаций, в частности по программной
инженерии)
– JoAnn T. Hackos. Information Development: Managing Your
Documentation Projects, Portfolio, and People.
– DITA Newsletter www.ditanewsletter.com
– Organization for the Advancement of Structured Information
Standards (OASIS) www.oasis-open.org
– Software Engineering Process Technology (SEPT) www.12207.com
Спасибо за внимание!
E-mail: estepalina@gmail.com
Блог: www.katyastep.wordpress.com
Вопросы?