Документирование

Июль 27, 2022

Главная
Информатика
Документирование

Содержание

2. Цели документирования Документация, создаваемая при разработке программных средств необходима для передачи информации между разработчиками ПС, управления
3. Классы документов Эту документацию можно разбить на две группы: документы управления разработкой ПС – документация проекта,
4. Документация проекта Документы управления разработкой ПС (process documentation), протоколируют процессы разработки и сопровождения ПС Они обеспечивают
5. Типы документов управления Планы, оценки, расписания. Эти документы создаются менеджерами для прогнозирования и управления процессами разработки
6. Типы документов управления Стандарты. Эти документы предписывают разработчикам, каким принципам, правилам, соглашениям они должны следовать в
7. Типы документов управления Рабочие документы. Это основные технические документы, обеспечивающие связь между разработчиками Они содержат фиксацию
8. Типы документов управления Заметки и переписка. Эти документы фиксируют различные детали взаимодействия между менеджерами и разработчиками
9. Документация продукта Документы, входящие в состав ПС (product documentation), описывают ПС с точки зрения его применения
10. Типы документов продукта Эти документы образуют два комплекта с разным назначением: пользовательская документация ПС (П-документация), документация
11. Пользовательская документация Пользовательская документация ПС (user documentation) объясняет пользователям, как они должны действовать, чтобы применить данное
12. Категории пользователей Следует различать две категории пользователей ПС: ординарных пользователей ПС и администраторов ПС Ординарный пользователь
13. Категории пользователей Администратор ПС (system administrator) управляет использованием ПС ординарными пользователями и осуществляет сопровождение ПС, не
14. Состав документации Состав пользовательской документации зависит от аудиторий пользователей, на которые ориентировано данное ПС, и от
15. Режим использования Под режимом использования документа понимается способ, определяющий, каким образом используется этот документ Обычно пользователю
16. Состав пользовательской документации Общее функциональное описание ПС с краткой характеристикой функциональных возможностей ПС. Предназначено для пользователей,
17. Состав пользовательской документации Инструкция по применению ПС. Предназначена для ординарных пользователей и содержит необходимую информацию по
18. Состав пользовательской документации Руководство по управлению ПС. Предназначено для системных администраторов и должно описывать сообщения, генерируемые
19. Разработка пользовательской документации Разработка пользовательской документации начинается сразу после создания внешнего описания и ее качество может
20. Разработка пользовательской документации Для обеспечения качества пользовательской документации разработан ряд стандартов, в которых предписывается порядок разработки
21. Документация сопровождения Документация по сопровождению ПС (system documentation) описывает ПС с точки зрения ее разработки Эта
22. Документация сопровождения В случае необходимости модернизации ПС к этой работе привлекается специальная команда разработчиков-сопроводителей Этой команде
23. Документация сопровождения Команда разработчиков-сопроводителей должна будет изучать эту документацию и затем вносить в нее необходимые изменения,
24. Документация сопровождения Документация по сопровождению ПС можно разбить на две группы: документация, определяющая строение программ и
25. Документация сопровождения Документация первой группы содержит итоговые документы каждого технологического этапа разработки ПС и включает следующие
26. Документация сопровождения Кроме того, для каждого модуля - его спецификация и описание его строения (design description);
27. Документация сопровождения Документы установления достоверности ПС включают прежде всего документацию по тестированию (схема тестирования и описание
28. Документация сопровождения Документация второй группы содержит Руководство по сопровождению ПС (system maintenance guide), которое описывает: известные
29. Проблема сопровождения ПС Общая проблема сопровождения ПС заключается в обеспечении согласованности всех его представлений при внесении
30. Автоматизация документирования Ввиду ограниченности сроков изготовления программных продуктов, они обычно плохо документируются Решению этой проблемы может
31. Генератор документации Генератор документации — программа или пакет программ, позволяющая получать документацию, предназначенную для программистов (документация
32. Принципы работы Генератор анализирует исходный код программы, выделяя синтаксические конструкции, соответствующие значимым объектам программы (типам, классам,
33. Документирующие комментарии Документирующие комментарии добавляются программистом в процессе написания программного кода и имеют вид /// ///
34. XML-файлы документации Файлы документации могут создаваться в процессе построения сборки Это возможность компилятора реализуется при установке
35. Генератор NDoc Существует большое число генераторов документации, ориентированных на те или иные языки и среды разработки
36. Генератор NDoc NDoc генерирует документацию библиотек классов на основе .NET сборок и XML-файлов документации, создаваемых компилятором
37. Генератор NDoc Энтузиазм Кевина Даунса не получил поддержки программистского сообщества и в конце июля 2006 года
38. Генератор Sandcastle В том же 2006 году стартует проект Microsoft, преследующий те же цели и получивший
39. Отличие от NDoc В Sandcastle основой всегда является сборка: на основе мета-информации сборки строится весь справочник,
40. Состав Sandcastle Sandcastle имеет два основных компонента: MrefBuilder – генерирует XML-файл, используя механизм отражения (reflection); BuildAssembler
41. Процесс формирования справочника Для каждого объекта исходной сборки – пространства имен, класса, свойства, метода и т.
42. Процесс формирования справочника Следующий шаг состоит в дополнении файла Reflection.xml серией дополнительных тэгов Для этого используются
43. Процесс формирования справочника В частности из Reflection.xml с помощью XSLT-преобразования получают все файлы, необходимые для сборки
44. Краткая схема работы Sandcastle C# or VB source files csc /doc assemblies XML files MrefBuilder +
45. Подробная схема работы Sandcastle
46. Sandcastle Help File Builder Все этапы формирования справочника могут быть выполнены в режиме командной строки Кроме
47. Установка SHFB Sandcastle Help File Builder (SHFB) является свободно распространяемой графической оболочкой над генератором документации Sandcastle
48. Окно SHFB
49. Проект SHFB Для построения справочника необходимо создать новый проект SHFB Затем добавить в него файл сборки
50. Построение проекта Следующий этап заключается в построении SHFB-проекта Documentation -> Build Project В результате получается файл
51. Конец лекции
53. Скачать презентацию

Слайд 2

Цели документирования
Документация, создаваемая при разработке программных средств необходима для
передачи информации между

разработчиками ПС,
управления разработкой ПС,
передачи пользователям информации, необходимой для применения и сопровождения ПС

Слайд 3

Классы документов
Эту документацию можно разбить на две группы:
документы управления разработкой

ПС – документация проекта,
документы, входящие в состав ПС – документация продукта

Слайд 4

Документация проекта
Документы управления разработкой ПС (process documentation), протоколируют процессы разработки и

сопровождения ПС
Они обеспечивают связи внутри коллектива разработчиков и между коллективом разработчиков и менеджерами, управляющими разработкой

Слайд 5

Типы документов управления
Планы, оценки, расписания. Эти документы создаются менеджерами для прогнозирования

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

Слайд 6

Типы документов управления
Стандарты. Эти документы предписывают разработчикам, каким принципам, правилам, соглашениям

они должны следовать в процессе разработки ПС
Стандарты могут быть как международными или национальными, так и специально созданными для организации, в которой ведется разработка данного ПС

Слайд 7

Типы документов управления
Рабочие документы. Это основные технические документы, обеспечивающие связь между

разработчиками
Они содержат фиксацию идей и проблем, возникающих в процессе разработки, описание используемых стратегий и подходов, а также рабочие (временные) версии документов, которые должны войти в ПС

Слайд 8

Типы документов управления
Заметки и переписка. Эти документы фиксируют различные детали взаимодействия

между менеджерами и разработчиками

Слайд 9

Документация продукта
Документы, входящие в состав ПС (product documentation), описывают ПС
с точки

зрения его применения пользователями,
с точки зрения его разработчиков и сопроводителей (в соответствии с назначением ПС)
Эти документы используются не только на стадии эксплуатации ПС, но и на стадии разработки для управления процессом его разработки

Слайд 10

Типы документов продукта
Эти документы образуют два комплекта с разным назначением:
пользовательская

документация ПС (П-документация),
документация по сопровождению ПС (С-документация)

Слайд 11

Пользовательская документация
Пользовательская документация ПС (user documentation) объясняет пользователям, как они

должны действовать, чтобы применить данное ПС
К этому типу документации относятся документы, которыми руководствуется пользователь:
при инсталляции ПС,
при применении ПС для решения своих задач,
при управлении ПС (например, когда данное ПС взаимодействует с другими системами).

Слайд 12

Категории пользователей
Следует различать две категории пользователей ПС:
ординарных пользователей ПС
и администраторов

ПС
Ординарный пользователь ПС (end-user) использует ПС для решения задач в своей предметной области и может не знать многих деталей работы компьютера или принципов программирования

Слайд 13

Категории пользователей
Администратор ПС (system administrator) управляет использованием ПС ординарными пользователями и

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

Слайд 14

Состав документации
Состав пользовательской документации зависит от аудиторий пользователей, на которые ориентировано

данное ПС, и от режима использования документов
Пользовательская документация должна содержать информацию, необходимую для каждой аудитории

Слайд 15

Режим использования
Под режимом использования документа понимается способ, определяющий, каким образом используется

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

Слайд 16

Состав пользовательской документации
Общее функциональное описание ПС с краткой характеристикой функциональных возможностей

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

Слайд 17

Состав пользовательской документации
Инструкция по применению ПС. Предназначена для ординарных пользователей и

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

Слайд 18

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

должно описывать сообщения, генерируемые при взаимодействии ПС с другими системами, а также способы реагирования на эти сообщения
Если ПС использует системную аппаратуру, то этот документ может объяснять, как сопровождать эту аппаратуру

Слайд 19

Разработка пользовательской документации
Разработка пользовательской документации начинается сразу после создания внешнего описания

и ее качество может существенно определять успех ПС
Она должна быть достаточно проста и удобна для пользователя, поэтому к созданию их окончательных вариантов часто привлекаются профессиональные технические писатели

Слайд 20

Разработка пользовательской документации
Для обеспечения качества пользовательской документации разработан ряд стандартов, в

которых
предписывается порядок разработки этой документации,
формулируются требования к каждому виду пользовательских документов,
определяются их структура и содержание

Слайд 21

Документация сопровождения
Документация по сопровождению ПС (system documentation) описывает ПС с точки

зрения ее разработки
Эта документация необходима, если предполагается изучение устройства ПС и модернизация его программ

Слайд 22

Документация сопровождения
В случае необходимости модернизации ПС к этой работе привлекается специальная

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

Слайд 23

Документация сопровождения
Команда разработчиков-сопроводителей должна будет изучать эту документацию и затем вносить

в нее необходимые изменения, повторяя в значительной степени технологические процессы, с помощью которых создавалось первоначальное ПС

Слайд 24

Документация сопровождения
Документация по сопровождению ПС можно разбить на две группы:
документация,

определяющая строение программ и структур данных ПС и технологию их разработки;
документацию, помогающую вносить изменения в ПС

Слайд 25

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

ПС и включает следующие документы:
внешнее описание ПС (Requirements document);
описание архитектуры ПС (description of the system architecture), включая внешнюю спецификацию каждой ее программы;
для каждой программы ПС - описание ее модульной структуры, включая внешнюю спецификацию каждого включенного в нее модуля;

Слайд 26

Документация сопровождения
Кроме того,
для каждого модуля - его спецификация и описание его

строения (design description);
тексты модулей на выбранном языке программирования (program source code listings);
документы установления достоверности ПС (validation documents), описывающие, как устанавливалась достоверность каждой программы ПС и как информация об установлении достоверности связывалась с требованиями к ПС

Слайд 27

Документация сопровождения
Документы установления достоверности ПС включают прежде всего документацию по тестированию

(схема тестирования и описание комплекта тестов), но могут включать и результаты других видов проверки ПС, например, доказательства свойств программ

Слайд 28

Документация сопровождения
Документация второй группы содержит Руководство по сопровождению ПС (system maintenance

guide), которое описывает:
известные проблемы, связанные с ПС,
какие части системы являются аппаратно- и программно-зависимыми,
возможности дальнейшего развития ПС

Слайд 29

Проблема сопровождения ПС
Общая проблема сопровождения ПС заключается в обеспечении согласованности всех

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

Слайд 30

Автоматизация документирования
Ввиду ограниченности сроков изготовления программных продуктов, они обычно плохо документируются
Решению

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

Слайд 31

Генератор документации
Генератор документации — программа или пакет программ, позволяющая получать документацию, предназначенную

для программистов (документация на API) и/или для конечных пользователей системы, по особым образом комментированному исходному коду и/или по исполняемым модулям, полученным на выходе компилятора

Слайд 32

Принципы работы
Генератор анализирует исходный код программы, выделяя синтаксические конструкции, соответствующие значимым

объектам программы (типам, классам, процедурам/функциям и т. п.)
В ходе анализа также используется мета-информация об объектах программы, представленная в виде документирующих комментариев
На основе всей собранной информации формируется готовая документация в одном из общепринятых форматов

Слайд 33

Документирующие комментарии
Документирующие комментарии добавляются программистом в процессе написания программного кода и

имеют вид
///

/// Текст комментария
///

Такие комментарии используются при формировании XML-файлов, которые описывают структуру проекта

Слайд 34

XML-файлы документации
Файлы документации могут создаваться в процессе построения сборки
Это возможность компилятора

реализуется при установке соответствующей опции:
Проект → Свойства… → Сборка → Вывод → XML-файл документации
Полученный файл документации размещается в папке bin\Debug

Слайд 35

Генератор NDoc
Существует большое число генераторов документации, ориентированных на те или иные

языки и среды разработки
Первым из генераторов, ориентированных на платформу .Net Framework, был генератор NDoc, разработанный Кевином Даунсом (Kevin Downs) в начале 2000-х годов

Слайд 36

Генератор NDoc
NDoc генерирует документацию библиотек классов на основе .NET сборок и

XML-файлов документации, создаваемых компилятором
NDoc использует подключаемые плагины для создания документации в различных форматах, в том числе:
формате справки MSDN (.CHM),
формате справки Visual Studio (HTML Help 2)
формате веб-страниц MSDN-онлайн

Слайд 37

Генератор NDoc
Энтузиазм Кевина Даунса не получил поддержки программистского сообщества и в

конце июля 2006 года он заявил о прекращении своей работы над проектом

Слайд 38

Генератор Sandcastle
В том же 2006 году стартует проект Microsoft, преследующий те

же цели и получивший название Sandcastle
Свойства Sandcastle:
создание документации в стиле справочника MSDN,
возможность включения авторских комментариев,
поддержка обощений и других возможностей .Net Framework

Слайд 39

Отличие от NDoc
В Sandcastle основой всегда является сборка: на основе мета-информации

сборки строится весь справочник, а файл XML-комментариев является необязательным;
В NDoc основным источником являются XML-комментарии, а мета-информация из сборки используется только для тех объектов, которые упоминаются в файле XML-комментариев

Слайд 40

Состав Sandcastle
Sandcastle имеет два основных компонента:
MrefBuilder – генерирует XML-файл, используя

механизм отражения (reflection);
BuildAssembler генерирует файлы, выполняет преобразования и т. д.
Действие начинается с работы утилиты MrefBuilder, которая получает информацию из сборки и выдает ее в выходной файл – Reflection.xml

Слайд 41

Процесс формирования справочника
Для каждого объекта исходной сборки – пространства имен, класса,

свойства, метода и т. п. – этот файл содержит свой тэг с подробным описанием
В готовом справочнике, каждому тэгу будет соответствовать свой HTML-файл описания

Слайд 42

Процесс формирования справочника
Следующий шаг состоит в дополнении файла Reflection.xml серией дополнительных

тэгов
Для этого используются XSLT-преобразования, которые выполняются утилитой XslTransform
В результате формируется ряд преобразованных .xml файлов, которые подаются на вход компонента BuildAssembler

Слайд 43

Процесс формирования справочника
В частности из Reflection.xml с помощью XSLT-преобразования получают все

файлы, необходимые для сборки справочника .CHM:
.HHC-файл содержания,
.HHK-файл предметного указателя,
.HHP-файл проекта справки

Слайд 44

Краткая схема работы Sandcastle
C# or VB
source files
csc /doc
assemblies
XML
files
MrefBuilder
+
xslTransform
Reflection.xml
+
Manifest
BuildAssembler
HTML
topics
project
file
TOC
file
indexes
Help Viewer
HTML Help

Compiler

Sandcastle Libraries

External Tools

Source Files

Слайд 45

Подробная схема работы Sandcastle

Слайд 46

Sandcastle Help File Builder
Все этапы формирования справочника могут быть выполнены в

режиме командной строки
Кроме того имеется возможность воспользоваться системой Sandcastle Help File Builder, в которой интегрированы средства Sandcastle и удобная инструментальная среда разработки

Слайд 47

Установка SHFB
Sandcastle Help File Builder (SHFB) является свободно распространяемой графической оболочкой

над генератором документации Sandcastle
Инсталлятор SHFB доступен по ссылке, приведенной на предыдущем слайде

Слайд 48

Окно SHFB

Слайд 49

Проект SHFB
Для построения справочника необходимо создать новый проект SHFB
Затем добавить в

него файл сборки и, опционально, xml-файл, полученный при компиляции

Слайд 50

Построение проекта
Следующий этап заключается в построении SHFB-проекта Documentation -> Build Project
В

результате получается файл в формате .chm, который может быть просмотрен либо с помощью web-браузера, либо с использованием специальных утилит (например, CHM Decoder)

Слайд 51

Документирование

Содержание

Цели документированияДокументация, создаваемая при разработке программных средств необходима дляпередачи информации между

Классы документовЭту документацию можно разбить на две группы: документы управления разработкой

Документация проектаДокументы управления разработкой ПС (process documentation), протоколируют процессы разработки и

Типы документов управленияПланы, оценки, расписания. Эти документы создаются менеджерами для прогнозирования

Типы документов управленияСтандарты. Эти документы предписывают разработчикам, каким принципам, правилам, соглашениям

Типы документов управленияРабочие документы. Это основные технические документы, обеспечивающие связь между

Типы документов управленияЗаметки и переписка. Эти документы фиксируют различные детали взаимодействия

Документация продуктаДокументы, входящие в состав ПС (product documentation), описывают ПСс точки

Типы документов продуктаЭти документы образуют два комплекта с разным назначением: пользовательская

Пользовательская документация Пользовательская документация ПС (user documentation) объясняет пользователям, как они

Категории пользователейСледует различать две категории пользователей ПС: ординарных пользователей ПСи администраторов

Категории пользователейАдминистратор ПС (system administrator) управляет использованием ПС ординарными пользователями и

Состав документацииСостав пользовательской документации зависит от аудиторий пользователей, на которые ориентировано

Режим использованияПод режимом использования документа понимается способ, определяющий, каким образом используется

Состав пользовательской документацииОбщее функциональное описание ПС с краткой характеристикой функциональных возможностей

Состав пользовательской документацииИнструкция по применению ПС. Предназначена для ординарных пользователей и

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

Разработка пользовательской документацииРазработка пользовательской документации начинается сразу после создания внешнего описания

Разработка пользовательской документацииДля обеспечения качества пользовательской документации разработан ряд стандартов, в

Документация сопровожденияДокументация по сопровождению ПС (system documentation) описывает ПС с точки

Документация сопровожденияВ случае необходимости модернизации ПС к этой работе привлекается специальная

Документация сопровожденияКоманда разработчиков-сопроводителей должна будет изучать эту документацию и затем вносить

Документация сопровожденияДокументация по сопровождению ПС можно разбить на две группы: документация,

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

Документация сопровожденияКроме того,для каждого модуля - его спецификация и описание его

Документация сопровожденияДокументы установления достоверности ПС включают прежде всего документацию по тестированию

Документация сопровожденияДокументация второй группы содержит Руководство по сопровождению ПС (system maintenance

Проблема сопровождения ПСОбщая проблема сопровождения ПС заключается в обеспечении согласованности всех

Автоматизация документированияВвиду ограниченности сроков изготовления программных продуктов, они обычно плохо документируютсяРешению

Генератор документацииГенератор документации — программа или пакет программ, позволяющая получать документацию, предназначенную

Принципы работыГенератор анализирует исходный код программы, выделяя синтаксические конструкции, соответствующие значимым

Документирующие комментарииДокументирующие комментарии добавляются программистом в процессе написания программного кода и

XML-файлы документацииФайлы документации могут создаваться в процессе построения сборкиЭто возможность компилятора

Генератор NDocСуществует большое число генераторов документации, ориентированных на те или иные

Генератор NDocNDoc генерирует документацию библиотек классов на основе .NET сборок и

Генератор NDocЭнтузиазм Кевина Даунса не получил поддержки программистского сообщества и в

Генератор SandcastleВ том же 2006 году стартует проект Microsoft, преследующий те

Отличие от NDocВ Sandcastle основой всегда является сборка: на основе мета-информации

Состав SandcastleSandcastle имеет два основных компонента: MrefBuilder – генерирует XML-файл, используя

Процесс формирования справочникаДля каждого объекта исходной сборки – пространства имен, класса,

Процесс формирования справочникаСледующий шаг состоит в дополнении файла Reflection.xml серией дополнительных

Процесс формирования справочникаВ частности из Reflection.xml с помощью XSLT-преобразования получают все

Краткая схема работы SandcastleC# or VBsource filescsc /docassembliesXMLfilesMrefBuilder +xslTransformReflection.xml+ManifestBuildAssemblerHTMLtopicsprojectfileTOCfileindexesHelp ViewerHTML Help