2.10 Разработка программной документации
Первым из документов, которые должны выпускаться в процессе проектирования, являются исходные требования к системе, согласованные между будущими пользователями и системным аналитиком. Многие части документации не имеют непосредственного отношения к программистам. В нее входят инструкции для персонала, занимающегося подготовкой входных данных, описания процедур контроля для управляющего персонала, описания тестовых процедур, а также рабочие инструкции для операторов.
В ходе проектирования выпускается документация двух типов - рабочая (промежуточная) и отчетная (окончательная). При разработке сложных проектов часто приходится выделять специального человека - секретаря проекта, который занимается оформлением документов и сбором рабочей документации. Любой программист вспомнит немало случаев, когда он выбрасывал распечатки старых вариантов программ, а впоследствии оказывалось, что без них не обойтись. Секретарь проекта как раз и занимается тем, сто подшивает все промежуточные распечатки, старые варианты блок-схем, спецификации, тестовые данные и т.п. , и хранит до тех пор, пока не завершатся окончательные испытания системы. Некоторые из рабочих документов должны в дальнейшем войти в состав отчетной документации.
Проектная документация служит основным источником информации, на основании которой осуществляется разработка системы, ее эксплуатация и обслуживание.
Рис. 2.4. Системная документация.
Требования к системе. Составление требований к системе не входит в задачу программистов. Они являются специалистами по программированию, а не по гражданскому строительству, банковскому делу, численным методам или в любых других прикладных областях. В то же время составление требований к системе не может быть поручено и одному лишь системному аналитику. Они должны вырабатываться в соответствии с официально оформленным договором между организацией-заказчиком и организацией-исполнителем и выражать содержание этого документа.
Проектная документация. Эта часть документации готовится системным аналитиком, который руководствуется сведениями, полученными от программистов и будущих пользователей.
Проект системы. К этим документам относится графические схемы задания и развернутые планы проекта, охватывающие структуру и основные детали программы.
Подготовка данных. Этот раздел охватывает все уровни организации данных, которые будут использоваться в программах, в том числе и справочники данных, описания файлов, таблицы ссылок и т.д.
Разработка программ. В этот раздел входят описания иерархической структуры программ в системе, потоков информации между программами и организации взаимодействия программ. Сюда же должна быть включена информация о внутреннем содержании программ, например описания алгоритмов, их блок-схемы или программы на псевдокоде.
Справочные пособия и руководства. Эти издания подготавливаются специалистами по технической документации, которые используют информацию, полученную от системного аналитика и программистов.
Руководство пользователя. В руководстве содержатся общее описание и подробные сведения о ее применении, разъясняются сообщения об ошибках.
Руководство по обслуживанию системы. В это руководство включаются отдельные разделы проектной документации и документы по реализации системы, необходимые для глубокого ознакомления с организацией данных и функциями программ.
Руководство оператора. В руководстве содержатся описание вычислительной установки и конфигурации устройств, а также инструкции по работе с программной системой
Реализация системы. Данная часть документации отражает результаты действия группы программирования.
Символьный код. Это набор текстов самодокументированных программ, составленных в удобной для восприятия форме.
Информация, выдаваемая ЭВМ. Сюда входят таблицы перекрестных ссылок, карты загрузки, таблицы атрибутов, данные о времени выполнения программ и любая другая машинная информация.
Тестовые прогоны программ. В эту часть документации включаются контрольные варианты входных данных и соответствующие результаты, получаемые в различных условиях. Указанная информация служит в качестве тестовой при проверке функционирования системы.
Промежуточная документация должна храниться вплоть до завершения работы над системой.
После того, как проектирование системы закончено, единственное назначение документации - обеспечить максимальную эффективность использования системы. Комплект документации строится по модульному принципу, но ее отдельные части в значительной степени перекрываются друг с другом.