Transcript Техническая коммуникация и документирование
Slide 1
Техническая коммуникация и
документирование ПО
Екатерина Степалина, SmartLabs
НИУ-ВШЭ
Slide 2
Зачем это мне?
• Вы получите представление о сфере
деятельности – технической коммуникации
(technical communication, TC).
• Вы познакомитесь с современными
средствами документирования
(documentation tools) программных систем.
• Вы узнаете лучшие практики (best practices)
документирования и некоторые приемы,
которые могут быть полезны уже сейчас.
Slide 3
Часть I
Техническая коммуникация
Slide 4
Средства коммуникации становятся
все более техническими
•
•
•
•
•
Бумажное письмо
Книга
…
Радио и ТВ
Графический пользовательский интерфейс
(GUI)
• Интернет
Slide 5
Мы используем всё больше
программ
• Производство, управление, обмен
информации автоматизируются с помощью
технических средств и программ.
• Люди используют всё больше программ в
различных сферах деятельности, в
повседневной жизни.
Slide 6
Как пользователи, мы хотим, чтобы
программы были удобными
Удобство (Usability) – одна из ключевых характеристик качества в
соответствии со стандартом ISO 9126.
Slide 7
Требуется все больше знаний в сфере
технической коммуникации, чтобы скрыть
сложность программы за простым
интерфейсом, чтобы сделать программу и
информацию о ней ПОНЯТНОЙ и
ЛЕГКОДОСТУПНОЙ.
Slide 8
Техническая коммуникация для
менеджера проекта
• На уровне компании - успешное
выполнение проекта и
обеспечение удовлетворенности
пользователя
• На уровне проекта – управление
коммуникациями в команде
• Для себя – развитие навыков
коммуникации как Soft Skills
Slide 9
Кто такие технические
коммуникаторы?
•
•
•
•
•
•
•
•
•
Дизайнеры (designers)
Технические писатели (technical writers)
Редакторы (editors)
Разработчики пользовательских интерфейсов и специалисты по
эргономике (UI developers, UI usability experts)
Разработчики обучающих курсов и учебных пособий (training
course developers)
Специалисты по информационной архитектуре (information
architects)
Специалистов по переводу, локализации,
интернационализации пользовательских интерфейсов
(translation, localization specialists)
Специалисты технической поддержки (Support engineers)
Специалисты по веб-маркетингу и рекламе (copy writers)
Slide 10
Slide 11
Society for Technical Communication
(STC)
• База по программам академической
подготовки в области TC
• Онлайн-учебные курсы
• Стажировки
• Общение и обмен опытом
Slide 12
Lynda.com
Более 900 курсов и 57 тысяч качественных
видеоуроков по инструментам и системам:
– Adobe Photoshop, Illustrator, InDesign
– Adobe Captivate
– Corel Draw
– Camtasia Studio
– AutoCAD
–…
Slide 13
Конференции
•
•
•
•
•
Конференция 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
Slide 14
Сделаем перерыв!
Slide 15
Часть II
Документирование ПО
Slide 16
Документирование ПО
превращается в глобальное
сопровождение продукта и требует
специальных знаний в сфере ТС.
Slide 17
Виды документов
Проектная
документация
Технические
документы
Комментарии
кода
Пользовательская документация
Slide 18
Проектные документы
• Техническое задание (ТЗ),
или software requirements
specification (SRS)
• План проекта
• Программа и методика
испытаний
• UML-диаграммы
проектируемой системы
Slide 19
Инструменты разработки проектной
документации
Документ
Инструмент (система)
Техническое задание
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
Slide 20
Пользовательские документы
• Руководства и инструкции (User Guide,
User Manual)
• Справки по функциям продукта (Reference)
• Описание изменений версии продукта
(Release Notes)
• Ответы на вопросы (Frequently Asked
Questions)
• Решение известных проблем
(Troubleshooting)
• Статьи How-To
• Статьи о лучших практиках (Best Practices)
• Мультимедиа-гиды (screencasts, podcasts)
Slide 21
Технические документы
• Спецификации оборудования,
систем (datasheet)
• Спецификации стандартов (RFC)
• Регламенты кодирования (coding
conventions)
Slide 22
Документация кода
• Описание программных интерфейсов (API)
• Описание классов, их методов и свойств
• Описание недокументированных
возможностей платформы
• Комментарии узких мест реализации
• Утилиты: JavaDoc, Doxygen
Slide 23
Наиболее трудоемким является
процесс разработки информации
(J.T. Hackos)
• Планирование информации (Information
Planning, 10%)
• Проектирование (Information Design, 20%)
• Разработка (Information Development, 50%)
• Эксплуатация (Production,20%)
• Оценивание (Evaluation, менее 1%)
Slide 24
Стадии разработки документации
Slide 25
Что нужно для разработки
документации?
Slide 26
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 (Совместная работа)
Slide 27
Стандарты – Национальные (РФ)
Российские стандарты основываются на ключевых международных стандартах:
• «ГОСТ Р ИСО 9001-2008. Системы менеджмента качества»
• «ГОСТ Р ИСО/МЭК 12207-99. Информационная технология. Процессы жизненного цикла
программных средств»
.
Действующие российские стандарты:
«ГОСТ Р ИСО/МЭК 15910-2002. Информационная технология. Процесс создания документации
пользователя программного средства»
«ГОСТ Р ИСО/МЭК ТО 9294-93. Информационная технология. Руководство по управлению
документированием программного обеспечения»
«ГОСТ Р ИСО 9127-94. Системы обработки информации. Документация пользователя и
информация на упаковке для потребительских программных пакетов»
Устаревшие, но все еще использующиеся стандарты:
• GOST 19.хх - - ГОСТы серии ЕСПД (Единая система программной документации). Это
стандарты 80-90-х годов. Они содержат требования к оформлению руководств пользователя и
программиста, схем алгоритмов, схем данных, спецификации на программный продукт.
• GOST 34.хх – Автоматизированные системы. Комплекс стандартов на автоматизированные
системы.
Самый популярный документ из этой серии - ГОСТ 34.602-89 Техническое задание на
создание автоматизированной системы. Это требования к оформлению ТЗ на АС, которые
часто применяются для информационных систем, разрабатываемых для государственных
организаций, учреждений и т.п.
Slide 28
Стандарты - Международные
Международные стандарты основываются на ключевых стандартах
в области разработки ПО:
• 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.
Slide 29
Принцип единого источника
• Публикация документов в
нескольких форматах (В Word,
CHM) из единого источника
• Совместная работа группы
авторов
• Многократное использование
одних и тех же блоков контента
(content re-use)
• Единая система индексов для всех
видов выходной документации
Slide 30
Как это реализовано?
Slide 31
Информационная архитектура
OASIS (Organization for Advancement of
Structured Information Standards)
разрабатывает и поддерживает схемы –
«фреймворки» для создания
информационной архитектуры.
• DocBook (1991, HAL Computer Systems,
O’Relly)
• DITA (2001, IBM)
Slide 32
DocBook
• Структурно-ориентированная система:
раздел, подраздел, пункт, абзац
• Подходит для разработки некоторых видов
проектных и пользовательских документов
• Меньшая гибкость, по сравнению с DITA
Slide 33
DocBook
Slide 34
DITA (Darwin Information Typing
Architecture)
• Семантическая модель информационных
типов
• Разбиение документа на «топики» по смыслу:
«Task», «Question», «Workaround»
• Возможность добавления собственных типов,
поддержка наследования
• Специальные средства контроля локализации
• Нет готовых решений, требует доработки и
настройки
Slide 35
DITA
Slide 36
Системы документирования
• Интегрированные среды разработки
документов (help authoring tools)
• Специальные CMS - Wiki-системы
• XML CMS, поддерживающие стандарт DITA
Slide 37
Help Authoring Tools
•
•
•
•
•
•
•
Author-it
Adobe RoboHelp
MadCap Flare
Help&Manual
EMC Documentum
Dr. Explain
MindTouch
Slide 38
Wiki-системы
•
•
•
•
•
MediaWiki
TWiki
PmWiki
DokuWiki
Confluence
Slide 39
XML CMS для работы с DITA
•
•
•
•
•
•
Horizon
XDocs
X-Hive/Docato
TEXTML Server (DITA CMS Framework)
Contenta
SiberSafe
Slide 40
Какую систему выбрать?
• Быстрый старт – достаточно Wiki
• По возрастанию стоимости
внедрения: Wiki, Help authoring
tools, XML CMS
• Wiki используют в небольших и
средних компаниях.
• Help authoring tools применяются в
средних и крупных организациях
NASA, NEC, Gartner.
• XML CMS используется в Adobe,
Boeing, Nokia, IBM, Oracle и др.
Slide 41
Форматы пользовательских
документов
• Печатные документы в формате PDF, MS
Word
• Онлайн-ресурсы (Wiki, блоги)
• Онлайн-справочные системы (WebHelp)
• Контекстные справки (HTML Help, MS Help
2, JavaHelp, FlashHelp)
• Электронные книги (ePub, FB2)
Slide 42
Стили изложения и оформления
• APA Style (Оформление публикаций,
наглядных пособий, презентаций)
• IEEE Style (Для оформления стандартов
IEEE)
• MLA Style (Оформление научных
статей)
• ESL Standards (Подготовка публикаций
для международного читателя)
• O'Relly Stylesheet and Word List
(Оформление печатных изданий, это
руководство используется
издательством O'Relly, которое
выпускает техническую литературу)
Slide 43
Поиск….
Уделите особое
внимание
подбору
ключевых слов.
Slide 44
Как отличить хорошую
документацию от плохой?
• Ориентируйтесь на задачи, которые хочет
выполнить пользователь, а не на «фичи» продукта.
• Ориентируйтесь на конкретный класс
пользователей.
• Используйте словарь терминов – глоссарий.
• Включайте только ту информацию, которая
действительно нужна пользователю.
• Побуждайте пользователя изучать возможности
системы через ее интерфейс.
• Используйте текст повторно для снижения
трудозатрат на разработку документации.
Slide 45
А как же картинки?..
Slide 46
Эдварт Тафт (Edward Tufte): «Настоящее
искусство – когда у наблюдателя за мгновение
возникает множество идей при том, что Вы
потратили всего каплю чернил на клочке
бумаги».
Slide 47
Заключение
• Техническая коммуникация (TC) – актуальная и
активно развивающаяся область знаний,
объединяющая представителей различных
профессий – от дизайнера и технического писателя
до специалиста по информационной архитектуре и
разработчика пользовательского интерфейса.
• Документирование – один из важных разделов TC,
который охватывает информационную поддержку и
сопровождение продукта, требует тщательной
разработки информационной архитектуры и
правильного выбора инструментов.
Slide 48
Узнать больше - 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
Slide 49
Узнать больше - Документирование
• Книги на русском языке:
– Липаев В.В. Документирование сложных программных средств.
– Ю.В. Кагарлицкий. Разработка документации пользователя
программного продукта. Методика и стиль изложения.
– В. Глаголев. Разработка технической документации. Руководство
для технических писателей и локализаторов ПО.
• Мировые бестселлеры и мейнстрим:
– 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
Slide 50
Спасибо за внимание!
E-mail: [email protected]
Блог: www.katyastep.wordpress.com
Slide 51
Вопросы?
Техническая коммуникация и
документирование ПО
Екатерина Степалина, SmartLabs
НИУ-ВШЭ
Slide 2
Зачем это мне?
• Вы получите представление о сфере
деятельности – технической коммуникации
(technical communication, TC).
• Вы познакомитесь с современными
средствами документирования
(documentation tools) программных систем.
• Вы узнаете лучшие практики (best practices)
документирования и некоторые приемы,
которые могут быть полезны уже сейчас.
Slide 3
Часть I
Техническая коммуникация
Slide 4
Средства коммуникации становятся
все более техническими
•
•
•
•
•
Бумажное письмо
Книга
…
Радио и ТВ
Графический пользовательский интерфейс
(GUI)
• Интернет
Slide 5
Мы используем всё больше
программ
• Производство, управление, обмен
информации автоматизируются с помощью
технических средств и программ.
• Люди используют всё больше программ в
различных сферах деятельности, в
повседневной жизни.
Slide 6
Как пользователи, мы хотим, чтобы
программы были удобными
Удобство (Usability) – одна из ключевых характеристик качества в
соответствии со стандартом ISO 9126.
Slide 7
Требуется все больше знаний в сфере
технической коммуникации, чтобы скрыть
сложность программы за простым
интерфейсом, чтобы сделать программу и
информацию о ней ПОНЯТНОЙ и
ЛЕГКОДОСТУПНОЙ.
Slide 8
Техническая коммуникация для
менеджера проекта
• На уровне компании - успешное
выполнение проекта и
обеспечение удовлетворенности
пользователя
• На уровне проекта – управление
коммуникациями в команде
• Для себя – развитие навыков
коммуникации как Soft Skills
Slide 9
Кто такие технические
коммуникаторы?
•
•
•
•
•
•
•
•
•
Дизайнеры (designers)
Технические писатели (technical writers)
Редакторы (editors)
Разработчики пользовательских интерфейсов и специалисты по
эргономике (UI developers, UI usability experts)
Разработчики обучающих курсов и учебных пособий (training
course developers)
Специалисты по информационной архитектуре (information
architects)
Специалистов по переводу, локализации,
интернационализации пользовательских интерфейсов
(translation, localization specialists)
Специалисты технической поддержки (Support engineers)
Специалисты по веб-маркетингу и рекламе (copy writers)
Slide 10
Slide 11
Society for Technical Communication
(STC)
• База по программам академической
подготовки в области TC
• Онлайн-учебные курсы
• Стажировки
• Общение и обмен опытом
Slide 12
Lynda.com
Более 900 курсов и 57 тысяч качественных
видеоуроков по инструментам и системам:
– Adobe Photoshop, Illustrator, InDesign
– Adobe Captivate
– Corel Draw
– Camtasia Studio
– AutoCAD
–…
Slide 13
Конференции
•
•
•
•
•
Конференция 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
Slide 14
Сделаем перерыв!
Slide 15
Часть II
Документирование ПО
Slide 16
Документирование ПО
превращается в глобальное
сопровождение продукта и требует
специальных знаний в сфере ТС.
Slide 17
Виды документов
Проектная
документация
Технические
документы
Комментарии
кода
Пользовательская документация
Slide 18
Проектные документы
• Техническое задание (ТЗ),
или software requirements
specification (SRS)
• План проекта
• Программа и методика
испытаний
• UML-диаграммы
проектируемой системы
Slide 19
Инструменты разработки проектной
документации
Документ
Инструмент (система)
Техническое задание
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
Slide 20
Пользовательские документы
• Руководства и инструкции (User Guide,
User Manual)
• Справки по функциям продукта (Reference)
• Описание изменений версии продукта
(Release Notes)
• Ответы на вопросы (Frequently Asked
Questions)
• Решение известных проблем
(Troubleshooting)
• Статьи How-To
• Статьи о лучших практиках (Best Practices)
• Мультимедиа-гиды (screencasts, podcasts)
Slide 21
Технические документы
• Спецификации оборудования,
систем (datasheet)
• Спецификации стандартов (RFC)
• Регламенты кодирования (coding
conventions)
Slide 22
Документация кода
• Описание программных интерфейсов (API)
• Описание классов, их методов и свойств
• Описание недокументированных
возможностей платформы
• Комментарии узких мест реализации
• Утилиты: JavaDoc, Doxygen
Slide 23
Наиболее трудоемким является
процесс разработки информации
(J.T. Hackos)
• Планирование информации (Information
Planning, 10%)
• Проектирование (Information Design, 20%)
• Разработка (Information Development, 50%)
• Эксплуатация (Production,20%)
• Оценивание (Evaluation, менее 1%)
Slide 24
Стадии разработки документации
Slide 25
Что нужно для разработки
документации?
Slide 26
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 (Совместная работа)
Slide 27
Стандарты – Национальные (РФ)
Российские стандарты основываются на ключевых международных стандартах:
• «ГОСТ Р ИСО 9001-2008. Системы менеджмента качества»
• «ГОСТ Р ИСО/МЭК 12207-99. Информационная технология. Процессы жизненного цикла
программных средств»
.
Действующие российские стандарты:
«ГОСТ Р ИСО/МЭК 15910-2002. Информационная технология. Процесс создания документации
пользователя программного средства»
«ГОСТ Р ИСО/МЭК ТО 9294-93. Информационная технология. Руководство по управлению
документированием программного обеспечения»
«ГОСТ Р ИСО 9127-94. Системы обработки информации. Документация пользователя и
информация на упаковке для потребительских программных пакетов»
Устаревшие, но все еще использующиеся стандарты:
• GOST 19.хх - - ГОСТы серии ЕСПД (Единая система программной документации). Это
стандарты 80-90-х годов. Они содержат требования к оформлению руководств пользователя и
программиста, схем алгоритмов, схем данных, спецификации на программный продукт.
• GOST 34.хх – Автоматизированные системы. Комплекс стандартов на автоматизированные
системы.
Самый популярный документ из этой серии - ГОСТ 34.602-89 Техническое задание на
создание автоматизированной системы. Это требования к оформлению ТЗ на АС, которые
часто применяются для информационных систем, разрабатываемых для государственных
организаций, учреждений и т.п.
Slide 28
Стандарты - Международные
Международные стандарты основываются на ключевых стандартах
в области разработки ПО:
• 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.
Slide 29
Принцип единого источника
• Публикация документов в
нескольких форматах (В Word,
CHM) из единого источника
• Совместная работа группы
авторов
• Многократное использование
одних и тех же блоков контента
(content re-use)
• Единая система индексов для всех
видов выходной документации
Slide 30
Как это реализовано?
Slide 31
Информационная архитектура
OASIS (Organization for Advancement of
Structured Information Standards)
разрабатывает и поддерживает схемы –
«фреймворки» для создания
информационной архитектуры.
• DocBook (1991, HAL Computer Systems,
O’Relly)
• DITA (2001, IBM)
Slide 32
DocBook
• Структурно-ориентированная система:
раздел, подраздел, пункт, абзац
• Подходит для разработки некоторых видов
проектных и пользовательских документов
• Меньшая гибкость, по сравнению с DITA
Slide 33
DocBook
Slide 34
DITA (Darwin Information Typing
Architecture)
• Семантическая модель информационных
типов
• Разбиение документа на «топики» по смыслу:
«Task», «Question», «Workaround»
• Возможность добавления собственных типов,
поддержка наследования
• Специальные средства контроля локализации
• Нет готовых решений, требует доработки и
настройки
Slide 35
DITA
Slide 36
Системы документирования
• Интегрированные среды разработки
документов (help authoring tools)
• Специальные CMS - Wiki-системы
• XML CMS, поддерживающие стандарт DITA
Slide 37
Help Authoring Tools
•
•
•
•
•
•
•
Author-it
Adobe RoboHelp
MadCap Flare
Help&Manual
EMC Documentum
Dr. Explain
MindTouch
Slide 38
Wiki-системы
•
•
•
•
•
MediaWiki
TWiki
PmWiki
DokuWiki
Confluence
Slide 39
XML CMS для работы с DITA
•
•
•
•
•
•
Horizon
XDocs
X-Hive/Docato
TEXTML Server (DITA CMS Framework)
Contenta
SiberSafe
Slide 40
Какую систему выбрать?
• Быстрый старт – достаточно Wiki
• По возрастанию стоимости
внедрения: Wiki, Help authoring
tools, XML CMS
• Wiki используют в небольших и
средних компаниях.
• Help authoring tools применяются в
средних и крупных организациях
NASA, NEC, Gartner.
• XML CMS используется в Adobe,
Boeing, Nokia, IBM, Oracle и др.
Slide 41
Форматы пользовательских
документов
• Печатные документы в формате PDF, MS
Word
• Онлайн-ресурсы (Wiki, блоги)
• Онлайн-справочные системы (WebHelp)
• Контекстные справки (HTML Help, MS Help
2, JavaHelp, FlashHelp)
• Электронные книги (ePub, FB2)
Slide 42
Стили изложения и оформления
• APA Style (Оформление публикаций,
наглядных пособий, презентаций)
• IEEE Style (Для оформления стандартов
IEEE)
• MLA Style (Оформление научных
статей)
• ESL Standards (Подготовка публикаций
для международного читателя)
• O'Relly Stylesheet and Word List
(Оформление печатных изданий, это
руководство используется
издательством O'Relly, которое
выпускает техническую литературу)
Slide 43
Поиск….
Уделите особое
внимание
подбору
ключевых слов.
Slide 44
Как отличить хорошую
документацию от плохой?
• Ориентируйтесь на задачи, которые хочет
выполнить пользователь, а не на «фичи» продукта.
• Ориентируйтесь на конкретный класс
пользователей.
• Используйте словарь терминов – глоссарий.
• Включайте только ту информацию, которая
действительно нужна пользователю.
• Побуждайте пользователя изучать возможности
системы через ее интерфейс.
• Используйте текст повторно для снижения
трудозатрат на разработку документации.
Slide 45
А как же картинки?..
Slide 46
Эдварт Тафт (Edward Tufte): «Настоящее
искусство – когда у наблюдателя за мгновение
возникает множество идей при том, что Вы
потратили всего каплю чернил на клочке
бумаги».
Slide 47
Заключение
• Техническая коммуникация (TC) – актуальная и
активно развивающаяся область знаний,
объединяющая представителей различных
профессий – от дизайнера и технического писателя
до специалиста по информационной архитектуре и
разработчика пользовательского интерфейса.
• Документирование – один из важных разделов TC,
который охватывает информационную поддержку и
сопровождение продукта, требует тщательной
разработки информационной архитектуры и
правильного выбора инструментов.
Slide 48
Узнать больше - 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
Slide 49
Узнать больше - Документирование
• Книги на русском языке:
– Липаев В.В. Документирование сложных программных средств.
– Ю.В. Кагарлицкий. Разработка документации пользователя
программного продукта. Методика и стиль изложения.
– В. Глаголев. Разработка технической документации. Руководство
для технических писателей и локализаторов ПО.
• Мировые бестселлеры и мейнстрим:
– 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
Slide 50
Спасибо за внимание!
E-mail: [email protected]
Блог: www.katyastep.wordpress.com
Slide 51
Вопросы?