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

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

Лекция 13

2. Цели документирования

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

3. Классы документов

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

4. Документация проекта

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

5. Типы документов управления

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

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

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

7. Типы документов управления

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

8. Типы документов управления

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

9. Документация продукта

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

10. Типы документов продукта

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

11. Пользовательская документация

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

12. Категории пользователей

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

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. Документирующие комментарии

Документирующие комментарии
добавляются программистом в процессе
написания программного кода и имеют
вид
/// <summary>
/// Текст комментария
/// </summary>
Такие комментарии используются при
формировании 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. Процесс формирования справочника

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

42. Процесс формирования справочника

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

43. Процесс формирования справочника

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

44. Краткая схема работы Sandcastle

C# or VB
source files
csc /doc
assemblies
MrefBuilder
+
xslTransform
XML
files
Help Viewer
HTML Help
Compiler
Sandcastle Libraries
HTML
topics
project
file
Reflection.xml
+
Manifest
BuildAssembler
TOC
file
External Tools
indexes
Source Files
44

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. Конец лекции

52. Итоговый справочник