КомпанияУслугиСтатьиСервисы

Разработка технической документации в сфере ИТ: большой выездной тренинг

Версия для печати

Мероприятие проводится только в корпораивном режиме.

Длительность: 3 дня.

Макс. численность группы: 40 чел.

ОткрытыйКорпоративныйДоп. материалы
у себя в офисев «Философте»
-150 000,00 р.200 000,00 р.-

Аудитория и основные особенности тренинга

Большой выездной тренинг по документированию адресован, в первую очередь, крупным организациям, в которых разработкой технической документации заняты разные сотрудники: аналитики, проектировщики систем, технические писатели, руководители проектов и др.

Тренинг проводится на территории организации-заказчика в течение трех дней и охватывает широкий круг вопросов, связанных с разработкой технической документации в области информационных технологий. Он позволяет крупной организации в сжатые сроки и сравнительно небольшими затратами провести обучение сотрудников, обеспечив каждому из них необходимые знания и умения.

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

План тренинга

Тренинг построен таким образом, чтобы каждый участник мог изучить тот материал, который представляет для него наибольший интерес, и не тратить время на материал, который кажется ему избыточным. Он состоит из 12 независимых модулей, организованных в два параллельных потока: «инженерный» и «гуманитарный». Участники тренинга могут свободно выбирать нужные им модули, переходя с потока на поток. Более того, участник тренинга не обязан тратить на него все три дня: он может посетить только не те модули, которые ему необходимы.

День Время Инженерный поток Гуманитарный поток
I до обеда 1. Стандарты в области разработки программной и системной документации 7. Организация и планирование работы технического писателя
после обеда 2. Документирование автоматизированной системы в соответствии с требованиями ГОСТ 8. Номенклатура документов и проектирование комплекта документации
II до обеда 3. Применение XML-технологий для разработки технической документации. DocBook/XML 9. Содержание документа и его структура
после обеда 4. Разработка и сопровождение крупных комплектов технической документации на основе единого источника 10. Расположение материала в разделе и устойчивые формулы описания
III до обеда 5. Требования к технической документации 11. Язык и стиль документации
после обеда 6. Управление документированием в проекте и на предприятии 12. Авторская разметка документа и аппарат публикации

Единственное (очевидное) ограничение — невозможно участвовать в двух модулях, которые назначены на одно и то же время.

Программа тренинга

1. Стандарты в области разработки программной и системной документации

Нормативно-правовая база применения стандартов в России. Закон о техническом регулировании. Основные типы нормативно-технических документов. При каких условиях требования стандартов становятся обязательными.

Основные типы продукции в сфере ИТ. Технические средства. Программные средства. Информационные средства. Аппаратно-программные комплексы. Системы (в т. ч. автоматизированные).

Стандарты на техническую документацию и процессы документирования. «Классические» ГОСТы. Стандарты ИСО/МЭК в области системной и программной инженерии. Стандарты IEEE. Опубликованные методологии и библиотеки практик. Понятие профиля стандартов. Подбор профиля стандартов для использования в проекте, его обоснование перед заказчиком.

2. Документирование автоматизированной системы в соответствии с требованиями ГОСТ

Комплекс стандартов на автоматизированные системы (КСАС). Сфера действия КСАС, его состав и логика. Смежные комплексы стандартов.

Терминология и понятийный аппарат КСАС. Определение автоматизированной системы. Функции и задачи. Компоненты. Виды обеспечения. Стадии создания.

Техническая документация на автоматизированную систему. Отчет об обследовании. Концепция. Техническое задание. Документы эскизного и технического проекта. Программа и методика испытаний. Эксплуатационная документация.

3. Применение XML-технологий для разработки технической документации. DocBook/XML

XML: основные идеи и понятия. XML-документ, элементы, атрибуты. Хорошо оформленные документы. Язык XML и его приложения. DTD, схемы. Валидные документы. Преобразование XML-документов, язык XSLT.

Структурированная техническая документация. Язык разметки DocBook/XML. Преимущества функциональной разметки перед оформительской разметкой. Условный текст. Разбиение документа на модули. Для сравнения: представление о технологии DITA.

Публикация XML-документов. Преобразование документа из формата DocBook/XML в форматы HTML, PDF, CHM. Использование скриптов автоматизации для формирования выходных документов.

Настройка оформления выходных документов. Стили DocBook XSL: настройка с помощью параметров, настройка с помощью «подмены» шаблонов. Для сравнения: использование средства подготовки технических публикаций Adobe FrameMaker для реализации сложного оформления документов формата PDF.

4. Разработка и сопровождение крупных комплектов технической документации на основе единого источника

Методы работы с единым источником. Параметризация. Профилирование. Компонентный подход: информационные типы, топики, карты.

Пример 1. Несколько моделей на общей технологической основе.

Пример 2. Аппаратно-программный комплекс в разных комплектациях.

Выводы. Отдача от использования единого источника. Когда целесообразно использование единого источника, а когда нет. Краткий обзор инструментов для работы с единым источником.

5. Требования к технической документации

Требования к требованиям: конструктивность, различимость, тестируемость, реалистичность, непротиворечивость, адекватность. Арбитраж, который всегда с тобой: критерий работоспособности требований. Требования-цели и требования-ценности. Требования-условия и требования-предписания.

Типы требований: функционально-коммуникативные, к составу комплекта, к структурам документов, к подробности и полноте изложения, к терминологии, к языку и стилю, к оформлению, к возможностям сопровождения, форматам конечных документов, к комплектности и способу поставки, прочие.

Процедура формирования требований. Выбор стратегии формирования требований: треугольник ресурсов. Участники процедуры формирования требований и их функции. Последовательность действий при формировании требований. Результат: план документирования.

6. Управление документированием в проекте и на предприятии

Участники разработки технической документации, их функции, компетенции, и полномочия. Основные участники работ: руководитель проекта, технический эксперт, разработчик технической документации, ответственный приемщик. Исполнители специальных и технических работ: переводчик, лит. редактор, корректор, верстальщик и др. Заинтересованные лица и группы влияния: пользователи, внутренние службы заказчика, «начальство».

Планирование работ по созданию комплекта технической документации. Нулевой цикл: формирование требований к комплекту. Адаптация абстрактного жизненного цикла в соответствии с требованиями к конкретному комплекту. Формирование списка необходимых работ и определение последовательности их выполнения. Оценка объемов и трудоемкости работ, нормы выработки для различных видов работ. Составление календарного плана с учетом стадий жизненного цикла разрабатываемого комплекта и состава необходимых работ.

Контроль. Цели и задачи контроля. Виды контроля: текущий контроль и контроль по результатам этапов. Методы контроля. Типичные риски, индикаторы и предвестники их реализации.

Сдача-приемка технической документации. Главный принцип: ко дню сдачи работы все требования фактически должны быть признаны выполненными. Стратегия «показал-утвердил». Стратегия этапов и доработок и ее обратная сторона — «эффект швабры». Сдача по закрытому списку.

7. Организация и планирование работы

Участники работы над документацией и их взаимодействие. Место технического писателя в современной IT-индустрии. Партнеры технического писателя на разных этапах его деятельности. Ориентация на пользователя: идеалы и действительность.

Подготовка документации на стадии разработки программного средства и на стадии формирования комплекта поставки. Работа технического писателя в составе команды разработчиков. Работа над документацией к готовом продукту.

Сроки выполнения работы и их оценка. Проблема планирования сроков. Методы оценки сроков: поминутный/почасовой, нисходящего проектирования. Метод ранжирования работ по их масштабу/объему и по сложности. Проблема соотношения сроков и качества работы. Основные факторы нарушения сроков и способы их преодоления.

8. Номенклатура документов и проектирование комплекта документации

Национальные стандарты и их особенности. Национальные стандарты в области технической документации. Единая система конструкторской документации (ГОСТ 2.xxx). Единая система программной документации (ГОСТ 19.xxx). Стандарты на разработку и сопровождение автоматизированных систем (ГОСТ 34.xxx). Область применения различных стандартов. Их совместное использование. Сильные и слабые стороны различных стандартов применительно к работе над пользовательской документацией.

Номенклатура документов. Документы, создаваемые на различных этапах жизненного цикла программного средства. Понятие эксплуатационной документации и ее специфика. Стандарты ГОСТ 19.xxx и ГОСТ 34.xxx об эксплуатационной документации. Пользовательская документация как часть эксплуатационной документации. Комплект документации с точки зрения коммуникативных задач документации и с точки зрения заданной номенклатуры. Достоинства и недостатки каждого из подходов. Рекомендуемая номенклатура документов, входящих в состав эксплуатационной документации. Способы профилирования документов: по адресату, по характеру информации, по степени подробности.

Формирование комплекта документации. Понятие комплекта документации. Принципы формирования комплекта. Традиционный принцип формирования комплекта и концепция типичного пользователя. Функционально-ролевой принцип. Оформление документации в виде единого документа. Стандарты ГОСТ 19.xxx и ГОСТ 34.xxx о комплекте эксплуатационной документации.

9. Содержание документа и его структура

Документ в составе комплекта документации. Связь между структурой (содержанием) документа и составом комплекта. Факторы отбора сведений для документа. Тройной принцип. Руководство пользователя — основной документ комплекта.

Требования к содержанию документа. Отбор информации. Интервью. Принцип условной самодостаточности текста. Требования к содержанию документа: достоверность, релевантность, понятность. Неверное или неточное описание. Понятие о тестировании документации. Внимание к нештатным ситуациям.

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

10. Расположение материала в разделе и устойчивые формулы описания

Расположение материала. Типы информации и их компоновка. Структурная информация и ее основные разновидности. Директивная информация и ее основные разновидности. Справочная информация и ее основные разновидности. Изложение с точки зрения пользователя. Изложение с точки зрения интерфейса (функциональной структуры) программы. Стандарт IEEE 1063–2001 о расположении материала и логике изложения. Неполное описание. Структурированное и неструктурированное описание объектов и функций.

Сложные случаи описания объектов. Ветвящиеся процедуры и типовые функции. Длинные перечисления и способы их оформления. Проблема повторяющихся описаний. Многомерные объекты и зацикленные определения. Реальное и виртуальное: объекты, образы, идентификаторы. Наглядные и строгие описания, индуктивная и дедуктивная последовательности изложения. Антропоморфизм описаний: плюсы и минусы.

Фигуры описания. Принцип унификации описания. Понятие фигуры описания. Стандартные формулы, заголовочные конструкции и грамматические модели. Вводные и вспомогательные конструкции. Описания объектов и отношений между ними. Процедуры, описания функций и практические рекомендации. Метатекст. Попытки составления словаря фигур описания и связанные с этим проблемы.

11. Язык и стиль документации

Лексика документации. Группы терминологии: предметная область, компьютер и его использование, элементы интерфейса. Согласование терминологии предметной области. Согласование компьютерной терминологии. Проблемы перевода англоязычной терминологии. Вспомогательная лексика и ее унификация. Слова-артикли. Слова-классификаторы. Слова-прослойки.

Язык и стиль. Языковая культура и понимание. Объективное и субъективное в стилистике. Основные позиции самопроверки. Группы слов, не рекомендуемых к употреблению в документации.

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

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

12. Авторская разметка документа и аппарат публикации

Основные виды авторской разметки текста. Понятие об авторской разметке текста. Понятие шаблона. Заголовки, их языковая форма и способы их нумерации. Многошаговые процедуры, их оформление. Ненумерованные перечисления, их оформление. Врезки разного типа: замечания, рекомендации, предупреждения.

Иллюстрации и таблицы. Иллюстрации, их разновидности. Особенности подготовки снимков фрагментов экрана («скриншотов»). Подрисуночные подписи. Нумерация иллюстраций. Таблицы, их названия и нумерация.

Аппарат публикации. Понятие об аппарате публикации. Оглавление. Перекрестные ссылки. Указатель (индекс). Виды указателей. Методика составления предметного указателя. Глоссарий.

© «Философт», 2008–2017

+7 (499) 500-44-77

mail@philosoft.ru

SpyLOG