8.1.3 План документирования

8.1.3 План документирования

8.1.3.1 Общие положения

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

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

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

План документирования должен охватывать следующие вопросы (но не ограничиваться ими):

a) рабочее наименование, назначение, область применения и ограничения по использованию планируемой документации;

b) спецификацию стиля в соответствии 8.2;

c) определение аудитории пользователей (см. 8.1.3.2);

d) обоснование причин использования документации данной аудиторией и ее целевое назначение;

e) содержание (план-проспект) документации, с оценкой ее постраничного объема, и соответствующие уточнения для других машинных носителей документации;

f) номенклатуру поставки — число печатных копий, наличие электронных копий, форматы дисков и файлов (включая версии программных средств) и откуда они могут быть поставлены;

g) установление собственника авторских прав на документацию и любых других прав собственности.

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

h) обеспечение перевода документации на другие языки. Примечание — Подробнее см. в приложении Е;

i) уровни (грифы) секретности и конфиденциальности (при необходимости);

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

k) методы и средства производства (тиражирования) и используемые версии данных средств;

l) структуру коллектива разработчиков документации и, возможно, плана выбора данной структуры.

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

m) взаимосвязи (подчиненности) проекта;

n) почасовую загрузку и зарплату персонала (руководство по оценке этих факторов приведено в приложении F);

o) требования к проектным ресурсам, включая информационные и прочие ресурсы, представляемые заказчиком, и срокам их представления;

р) метод передачи документатору информации об изменениях программного средства в процессе его разработки;

q) планы контроля изменений и сопровождения документации (факультативно);

г) планы проверки документации после ее создания;

s) календарное планирование (графики) по контрольным точкам (milestones), включая (при необходимости):

1) утверждение плана документирования,

2) подготовку, проверку и корректировку проекта каждого документа,

3) тестирование на практичность,

4) подготовку оригиналов фотошаблонов,

5) распечатку, переплетение и распространение документации.

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

Примечания

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

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