ЧЕЛОВЕЧЕСКИЙ ФАКТОР

Составление документов

Создание документации для компьютерных систем аналогично написанию прозы: все описания и прочие документы должны быть ясными, краткими, точными и полными. Редактирование текста выполняется по обычным правилам литературного языка, однако необходим и целый ряд дополнительных правил, касаю­щихся должного стиля, формата, содержания документа и вы­текающих из технической природы самого текста. Существуют несколько вопросов, на которые пишущий должен ответить пе­ред началом работы над описанием, чтобы правильно опреде­лить нужные стиль, форму и содержание документа для дости­жения максимальной эффективности [1, 12, 29]:

5. Какая информация должна быть документирована? Суще­ствуют ли какие-либо ее части, на которые должно быть обра­щено особое внимание? Важно сконцентрироваться на целевом назначении документа. Забота о представлении мельчайших подробностей может привести к неудаче в обеспечении связно­сти и удобочитаемости текста.

6. Для кого предназначен документ? Насколько отвлеченным может быть изложение материала? Должны быть определены потенциальные «читатели», а содержание документа необходи­мо привести в соответствие с их уровнем подготовки и требо­ваниями.

7. Способы решения каких задач хочет знать пользователь? Указания в этой части должны быть ясными и полными. Необ­ходимо заранее определить возможные ошибки пользователя и описать нужные действия по их исправлению.

8. Как будет использоваться описание? Например, учебное пособие и справочник существенно различаются по своему со­держанию и должны быть по-разному организованы. Содержи­мое любого описания должно соответствовать его предполагае­мому использованию.

9. Будут ли справочные материалы легкодоступными? Если нет, то описание должно быть исчерпывающим.

10. В каких условиях будет использоваться описание? Рабо­чие места различаются по свободной площади, поэтому размер и форма документов должны быть приспособлены к условиям, в которых они будут использоваться.

11. Сколько средств отпущено для выпуска документации? Сколько людей может быть привлечено и каков их уровень квалификации? Каков срок окончания работы над документа­цией? Тщательное планирование работы поможет уложиться в установленные временные и бюджетные ограничения.

12. Кто будет оценивать точность, полноту и ясность изложе­ния? Человек, который разбирается в данной области и знаком с предполагаемым кругом пользователей, должен проверить до­кументацию на наличие неточностей, пропусков, а также слов и фраз, которые могли бы внести путаницу.

13. Как документация будет обновляться и поддерживаться? Важно обеспечить механизм периодического пересмотра и внесе­ния изменений в документацию после того, как она была прове­рена и начала использоваться. В пересмотренной редакции опи­сания следует четко отметить абзацы, которые отличаются от предыдущего варианта. Одним из способов такой отметки изме­нений являются скобки на полях.