Документирование работ по проектированию программного изделия
8.4.1. Детальный проект программного изделия
По мере того, как проектирование продвигается к самому нижнему уровню декомпозиции, происходит создание документа Детальный проект программного изделия. Документирование должно проводиться одновременно с детальным проектированием, кодированием и тестированием. В больших проектах этот документ для удобства делают в нескольких томах.
Часть 1 документа содержит описание принятых стандартов на проектирование и кодирование используемых средств. Материал раздела подготавливается до того, как начинается работа по детальному проектированию и кодированию.
Часть 2 документа постепенно расширяется по мере разработки проекта. Структура этой части документа и идентификация разделов полностью соответствует программным компонентам программного изделия.
Основное требование, предъявляемое к содержанию документа, — его завершенность, т.е. полный охват всех требований к программному изделию, изложенных в соответствующем документе. Документ Детальный проект должен содержать таблицу перекрестных ссылок между отдельными требованиями к программному изделию и компонентами детального проекта.
8.4.2. Руководство пользователя программного изделия
Выходным результатом фазы, кроме документа Детальный проект, является документ Руководство пользователя. Документ предназначен для организации эффективной работы пользователя с программным изделием. При изложении материала целесообразно использовать два стиля описания: в виде инструкций (обучающий) и в справочном виде. В то время как стиль инструкций ориентируется на оказание помощи новым пользователям, справочный стиль предназначен для более опытных пользователей, которым требуется информация по более специфическим вопросам.
В секции инструкций материал Руководства должен быть упорядочен в соответствии с последовательностью обучения, начиная с простейших и наиболее необходимых операций, появляющихся в первую очередь, до более сложных, появляющихся позже.
Размер этой секции зависит либо от принятой методики обучения, либо от особенностей коллектива пользователей: некоторые из пользователей могут понять возможности и особенности использования программного изделия после знакомства с небольшим числом примеров, в то время как другим может потребоваться изучение многочисленных примеров.
В справочной секции представлены основные операции, упорядоченные для удобства использования, например, по алфавиту. Документация, представленная в этой секции, является более формальной, точной и исчерпывающей по сравнению с предыдущей. Например, команда в секции инструкций может быть описана в конкретных понятиях в виде отдельного рабочего примера, а в справочной секции должны быть описаны все возможные параметры, опции и ключевые слова с несколькими примерами, уточняющими их смысл.
В руководство целесообразно включать иллюстрации в виде экранов с описанием особенностей манипуляций на клавиатуре.
Разработка Руководства пользователя должна начинаться как можно раньше. Прежде всего должен быть определен круг читателей, т.к. этот момент в значительной степени определяет стиль изложения. Руководство пользователя может быть создано в качестве он-лайнового средства помощи, т.е. в виде специального программного продукта. В этом случае должны быть разработаны отдельные требования для его проектирования.
Руководство пользователя содержит следующие разделы:
• общие сведения;
• описание применения;
• требования к процедурам.
В первом, вводном, разделе обычно дается описание прикладной области и приводятся основные функции изделия, а также условия его функционирования.
Во втором разделе рассматриваются выполняемые функции, более подробно описывается назначение программного изделия, предоставляемые им возможности для пользователя и отмечаются преимущества, которые дает пользователю данное программное изделие. Значительное внимание уделяется описанию условий эксплуатации, используемого оборудования и программных средств.
Структура программного изделия дается с описанием роли каждой компоненты, а рабочие характеристики изделия — в виде описания функциональных возможностей с указанием, где это возможно, количественных параметров входных и выходных потоков, времени реакции и т.п. Отдельно описывается база данных с указанием каждого файла и его назначения. Особое внимание уделяется описанию потоков обрабатываемых данных и результирующих выходов с указанием их взаимосвязей.
В третьем, основном, разделе Руководства представлена информация о необходимых процедурах запуска системы, подготовки данных и настройки параметров. Здесь также представлены процедуры обработки ошибок, восстановления информации и требования к этим процедурам.
В процедурах запуска описывается каждый шаг процедур, необходимых для организации работы. Значительное внимание уделяется описанию процедур ввода данных, при этом определяются требования к процедуре подготовки данных: частоте ввода, источникам данных, носителям информации, ограничениям, контролям достоверности. Для организации ввода пользователю должны быть представлены макеты входных форм с подробным описанием назначения каждого реквизита, а для наиболее сложных форм целесообразно представить их образцы с сопутствующим описанием.
Затем должны быть описаны требования, предъявляемые к каждому выходному документу или экрану, указаны: способ использования и частота выдачи, способ представления (носитель), инструк-
65 ции по сохранению, распространению и т.д. В этом разделе должны быть представлены описания всех выходных форм и экранов с объяснением каждого конкретного раздела формы- По каждому типу результатов работы изделия должны быть представлены образцы с примерами результатов.
В отдельном подразделе Руководства приводятся возможные ошибки и процедуры их устранения. Здесь целесообразно перечислить коды возможных ошибок, возникающих при работе программ, и необходимые действия пользователя по восстановлению работоспособности программного изделия.
