| Введение |
| 1. | О процессе документирования в ИТ-подразделении |
| | 1.1. | Об основных компетенциях |
| | 1.2. | О работе технического писателя |
| 2. | Цели и принципы документирования программных средств |
| | 2.1. | Стандарты документирования программных средств |
| | 2.2. | Технологическая и эксплуатационная документация на программное средство |
| | | 2.2.1. | Технологическая документация |
| | | 2.2.2. | Эксплуатационная документация |
| | | 2.2.3. | Описание программы и применения |
| | | 2.2.4. | Описание языка |
| | | 2.2.5. | Руководство администратора |
| | | 2.2.6. | Руководство оператора |
| | | 2.2.7. | Руководство пользователя |
| | | 2.2.8. | Руководство программиста |
| | | 2.2.9. | Руководство системного администратора |
| | | 2.2.10. Справочная система |
| | 2.3. | Организация документирования программных средств |
| | | 2.3.1. | Процесс документирования |
| | | 2.3.2. | Документирование корпоративной информационной системы |
| | | 2.3.3. | Документирование комплектуемого решения |
| | 2.4. | Управление документированием этапов жизненного цикла программного средства |
| | | 2.4.1. | План выполнения документирования |
| | | 2.4.2. | Планирование качества документов |
| | | 2.4.3. | Архитектура системы документооборота |
| | | 2.4.4. | Конфигурационное управление документацией |
| | 2.5. | Документация управления качеством программного средства |
| | 2.6. | Структура и содержание документов по этапам жизненного цикла программного средства |
| | | 2.6.1. | Документы предварительных требований, спецификаций и ресурсов для разработки программного средства |
| | | 2.6.2. | Документы процессов проектирования и выбора характеристик качества программного средства |
| | | 2.6.3. | Документы процессов разработки и программирования компонентов программных средств |
| | | 2.6.4. | Документы верификации и тестирования компонентов программных средств |
| | | 2.6.5. | Документы квалификационного тестирования, испытаний и оценивания качества программных средств |
| | | 2.6.6. | Документы сопровождения и конфигурационного управления версиями программного средства |
| | | 2.6.7. | Документы процессов эксплуатации программных средств |
| | 2.7. | Состав пользовательской документации на программное средство |
| | | 2.7.1. | Предмет документирования |
| | | 2.7.2. | Комплект документации. Документ |
| | | 2.7.3. | Формальная структура документа |
| | | 2.7.4. | Типы информации в документе |
| | | 2.7.5. | Изложение материала в сплошном тексте |
| | | 2.7.6. | Слова и формулировки |
| | | 2.7.7. | Авторская разметка текста |
| | 2.8. | Техническое задание на проектирование |
| | | 2.8.1. | ГОСТ 19.201-78. Техническое задание. Требования к содержанию и оформлению |
| | | 2.8.2. | Простейший пример технического задания |
| | | 2.8.3. | Пример технического задания на электронный ресурс |
| | 2.9. | Эскизный, технический, рабочий проект программного средства |
| | 2.10. | Документация тестирования компонентов и комплексов программ |
| | 2.11. | Документация сопровождения и конфигурационного управления версиями программ |
| | | 2.11.1. Единицы конфигурационного управления |
| | | 2.11.2. Управление версиями |
| | | 2.11.3. Управление сборками |
| | | 2.11.4. Понятие baseline |
| | | 2.11.5. Стандартизация процесса управления конфигурацией |
| 3. | Пакеты программ для формирования отчетов |
| | 3.1. | Особенности работы в Microsoft Word и Open Office для технического писателя |
| | | 3.1.1. | Рекомендации по использованию стилей |
| | | 3.1.2. | Особенности оформления рисунков |
| | | 3.1.3. | Прочие рекомендации |
| | 3.2. | Экскурс в историю: система документирования Rational SoDA |
| | 3.3. | Технология единого источника |
| | | 3.3.1. | Общие сведения о технологии единого источника |
| | | 3.3.2. | Основные понятия и определения |
| | | 3.3.3. | Содержание, структура, оформление |
| | | 3.3.4. | Единый источник как база знаний |
| | | 3.3.5. | Технологическая платформа DocBook/XML |
| | | 3.3.6. | MadCap Flare: система для разработки технической документации на основе единого источника |
| | | 3.3.7. | Arbortext: система разработки, генерации и публикации технической документации |
| | 3.4. | Издательская система LAТеХ |
| Литература |
Учебное пособие является подробной реферативной подборкой материалов, так или иначе связанных с процессом документирования
программного средства. Дело в том, что информация по данному вопросу рассредоточена по огромному числу источников, и до сих пор
не было издано ни одного пособия для технического писателя.
Все вопросы программной инженерии, проектирования и организации работы над сложнымии программными средствами освещены
во второй части пособия "Проектирование программных средств".
Данная книга не является руководством пользователя по той или
иной программе, в ней описывается только процесс документирования, его основные этапы. В первой части рассказывается о процессе
документирования и его месте в работе IТ-подразделения, о работе
технического писателя. Во второй части подробно рассматриваются
различные виды программной документации и существующие российские и международные стандарты, знание которых необходимо техническому писателю. В третьей части приводится описание различных
современных издательских систем, используемых для создания документации различного уровня. Учебное пособие является навигатором
в области документирования программ и позволит читателю найти все
требуемые документы, обозначить содержание того или иного документа, выбрать издательскую систему для дальнейшей работы с документацией.
В тексте приведены примеры оглавлений некоторых документов, их краткое содержание и т.д.
Очевидно, что рассматриваемые в данном пособии принципы документирования программного средства никогда не будут реализованы:
описывается идеальная и самая сложная ситуация. Если руководствоваться абсолютно всеми данными, приведенными в учебном пособии,
при создании достаточно простой программы, можно оказаться попросту погребенным под кипой никому не нужных руководств и документации. Следование абсолютно всем рекомендациям учебного пособия
приемлемо для создания крупномасштабных проектов. В остальных
случаях рекомендуется в первую очередь руководствоваться правилами здравого смысла и создавать только те документы, в которых есть
необходимость.
Макаровских Татьяна Анатольевна