Типовые документы продукции включают в себя:
учебные руководства;
справочные руководства и руководства пользователя;
руководства по сопровождению программного обеспечения;
брошюры и информационные листовки, посвященные продукции.
7.2.3 Документация управления проектом
Документы создают на основе информации управления проектом, такой как:
графики для каждой стадии процесса разработки и отчеты об изменениях графиков;
отчеты о согласованных изменениях программного обеспечения;
отчеты о решениях, связанных с разработкой;
распределение обязанностей.
Данная документация обеспечивает информацию, относящуюся, с точки зрения руководства, к долговечности продукции.
7.3 Определение качества документов
Руководители должны выбирать стандарты, распространяющиеся на уровень качества, соответственно различным типам документов и различным типам проектов и должны определять, как это качество будет достигнуто и поддержано.
Понятия качества, применимые к содержанию, структуре и представлению документации:
1) качество содержания можно измерять в элементах точности, полноты и ясности;
2) качество структуры можно измерять легкостью, с которой читатель имеет возможность определить местоположение информации;
3) качество представления должно соответствовать типу проекта. Например, руководство пользователя может иметь форму набора машинописных страниц, скрепленных вместе, или может быть типографской книгой с обширными иллюстрациями, созданной специалистом по графике.
7.4 Определение форматов документов
Стандартизованные форматы документов важны для контроля качества документов, для читаемости документов и для облегчения их сопровождения.
Информация может быть представлена в различных форматах. Проектные спецификации, например, могут быть записаны на установленных бланках. Обучение пользователя можно осуществить посредством учебных программ в классах или учебных конспектов и консультаций.
Форматы документов могут различаться от проекта к проекту. Они зависят от таких факторов, как объем проекта, аудитория, для которой предназначены документы, количество установленных стадий и бюджет документирования.
В проектируемых форматах должны быть учтены соображения о том, будут ли документы переводить для международного распространения.
Стандарты и руководства данной организации, распространяющиеся на форматы документов, должны быть установлены таким образом, чтобы допускать гибкость для руководителей в выборе форматов, подходящих для их проектов.
7.5. Определение системы обозначения документов
Стандартные обозначения документов необходимы для эффективного контроля документации. Обозначающая информация может включать в себя:
заглавие документа;
ссылочный номер документа;
номер версии документа;
дату выпуска и пересмотра;
реквизиты автора;
реквизиты утвердившего лица;
обозначение защищенности (авторских прав);
обозначение организации.
Если документы выпускают в виде разрозненных листов, каждая страница должна иметь индивидуальное обозначение (например, со ссылочным номером документа, номером страницы и номером издания).
8 УСТАНОВЛЕНИЕ ПРОЦЕДУР ДОКУМЕНТИРОВАНИЯ
Должны быть установлены процедуры для применяемых в организациях стратегий документирования.
Процедуры определяют последовательность документирования: планирование; подготовка;
конфигурационное управление; проверка; утверждение; производство; хранение; дублирование;
распространение и модернизация; продажа.
Процедуры также должны определять контрольные пункты и методы обеспечения качества.
9 РАСПРЕДЕЛЕНИЕ РЕСУРСОВ ДЛЯ ДОКУМЕНТИРОВАНИЯ
Основными ресурсами, требуемыми для документирования, являются следующие:
персонал (см. 9.1);
средства (см. 9.2);
финансирование (см. 9.3).
9.1 Персонал
Для процесса разработки программного обеспечения необходимы люди со знанием:
программирования - для разработки программного обеспечения;
сути предмета - для представления информации о применениях программного обеспечения;
документирования - для разработки документации продукции,
Важно, чтобы штат был полностью обучен методам документирования и чтобы каждая группа полностью понимала и выполняла свою роль в документировании;
проектировщики программного обеспечения и программисты создают документацию разработки, которая описывает продукцию или ее задачи; они также обеспечивают документацию сопровождения программной продукции;
специалисты в предметной области обеспечивают информацию для (и могут разрабатывать) части стадий изучения, спецификаций требований, планов тестирования и обеспечения качества, планов сборки программного обеспечения в условиях эксплуатации и многих типов графиков;
специалисты по изданию обычно подготовляют документацию по обучению пользователя, а также справочную, информационную о продукции и посредническую.
9.2 Средства
Важно предусмотреть обеспечение задач документирования соответствующими и подходящими средствами.
Инструментальные программные средства полезны для подготовки и контроля документации. Они могут быть применены для повышения эффективности многих процессов документирования и использования стандартов данной организации, распространяющихся на документирование.
9.3 Финансирование
Важно, чтобы стоимость документирования определяли как отдельные статьи бюджета, так как она нередко составляет значительную часть стоимости разработки программного обеспечения.
10 ПЛАНИРОВАНИЕ ДОКУМЕНТИРОВАНИЯ
План документирования определяет, что должно быть сделано, как это должно быть сделано, когда это должно быть сделано и кто это должен делать.
План документирования может быть частью общего плана проектирования или отдельным документом. Для небольших, неофициальных проектов план может быть всего на одной странице. Для больших проектов это может быть объемный документ, который следует установленным стандартам и является предметом для официальной проверки и процедуры утверждения.
План документирования должен быть доведен до всех участников разрабатывающего коллектива и до всех, кого он касается. Должны быть четко установлены обязанности всех вовлеченных в работу, связанную с документированием.
План должен включать в себя изложение:
общей структуры документации;
типов и содержания документов;
качества и форматов документов;
обозначения документов;
комплектности и хранения документов;
обращения документов;
графика документирования.
График документирования должен распределять время для:
планирования документов;
проверки плана документирования и принципов документирования;
подготовки проектов и проверки их на техническую точность, полноту и соответствие;
редактирования при внесении комментариев, появившихся при проверке;
проведения согласования;
перевода (например, с японского на французский);
распространения.
Планирование следует начинать заранее, и план необходимо проверять на всем протяжении проекта. Подобно любому плану, план документирования отражает намечаемые действия и является объектом для необходимых изменений. В проекте должны быть предусмотрены регулярные проверки результативности изменений. в плане.
ПРИЛОЖЕНИЕ А (информационное)
КОНТРОЛЬНЫЕ ТАБЛИЦЫ ДЛЯ УПРАВЛЕНИЯ ПРОГРАММНОЙ ДОКУМЕНТАЦИЕЙ *
А1 Контрольная таблица стратегии
а) Будут ли решения направлены на:
1) создание соответствующей программной документации?
2) применение стандартов и руководств по документированию?
3) установление процедур документирования?
4) создание ресурсов, пригодных для документирования?
5) использование средств автоматизированного документирования?
6) определение штата с ответственностями за:
обеспечение стандартами и процедурами по документированию?
контроль качества документации?
б) Будет ли опубликован стратегический отчет?
А.2 Контрольная таблица стандартов
Будут ли приняты или определены стандарты для:
