2. Автор
• аналитик, технический
писатель, менеджер проектов,
консультант, тренер ( > 8 лет)
• преподаватель технического
ВУЗа ( > 15 лет)
• докладчик научно-
практических конференций
• модератор группы по изучению
стандарта BABOK
18.04.2015 И.Ямшанов, Telesens 2
3. Содержание
18.04.2015 И.Ямшанов, Telesens 3
• для кого пишется документ;
• цель написания;
• представление информации;
• обзор инструментария;
• процесс работы над документом (best
practices);
• что дальше?
4. Проблемы
18.04.2015 И.Ямшанов, Telesens 4
• Не хотят писать документы потому что:
• «это никому не нужно…»
• «и так все понятно…»
• «не понятно с чего начать и какой ожидается
результат…»
• Результат не соответствует ожиданиям и
потраченному времени
• Написанный документ сложно
поддерживать в актуальном состоянии
5. Читатель
18.04.2015 И.Ямшанов, Telesens 5
• «Внешний» или «внутренний»: формализм,
средства представления, язык, …
• Насколько «в теме»: знание бизнеса,
терминологии, наличие технического
бекграунда, …
• Несколько категорий читателей: единый
документ или отдельные
6. Цель
18.04.2015 И.Ямшанов, Telesens 6
• Экономия времени
• Выполнение обязательств
• Повторное использование
• Использование в процессе разработки
• В наказание
• Ваш вариант?
7. Средства (1)
18.04.2015 И.Ямшанов, Telesens 7
Структурирование информации:
• структура каталогов (проект/фаза/файл)
• структура документа (wiki)
Для документа:
• идентификатор XX99.AA.00.99.TT
• версия/ревизия и история изменений (номер, дата
изменения, кем менялось и суть изменений)
• колонтитулы (идентификатор, название, автор,
дата, копирайт)
• содержание
• ссылки
8. Средства (2)
18.04.2015 И.Ямшанов, Telesens 8
• Словарь
• Шаблоны и повторное использование
• Best practices:
• различия представлений
• правка по диагонали
• ревью после таймаута
• интеллектуальный copy/paste
• без количества
9. Инструментарий (1)
18.04.2015 И.Ямшанов, Telesens 9
• Модели
• пакеты (Enterprise Architect, Visual Paradigm,
Microsoft Visio)
• онлайн сервисы (Gliffy online, LucidChart;
Coggle, WiseMapping)
• редакторы общего назначения
Чеклист для выбора: стоимость, примитивы и
диаграммы, стандарты, кастомизация,
валидация, генерация документов, совместная
работа, интеграция
10. Инструментарий (2)
18.04.2015 И.Ямшанов, Telesens 10
• Изображения (Paint.NET, Evolus Pencil,
Balsamiq Mockups)
• Текст (Microsoft Office, Apache Open Office,
MediaWiki)
• Контроль версий (Git, Microsoft Visual
SourceSafe)
• Утилиты: скриншоты (Jing), …
11. Последовательность
18.04.2015 И.Ямшанов, Telesens 11
• Зависит от используемой методологии:
• включить в критерий готовности
• Включаем в план проекта:
• выбрать подходящее время
• План, структура, наполнение:
• содержимое каждого раздела
• форма, удобная для восприятия
12. Что дальше?
18.04.2015 И.Ямшанов, Telesens 12
• стандарты: IEEE Std 1063-2001,
ISO/IEC FDIS 18019:2004,
ISO/IEC 26514:2008,
ГОСТ Р ИСО 9127-94,
ГОСТ Р ИСО/МЭК 15910-2002
• techwriters.ru/forum/
• Липаев В.В. Документирование сложных
программных средств (2005, эл. версия)