Составление документов
Создание документации для компьютерных систем аналогично написанию прозы: все описания и прочие документы должны быть ясными, краткими, точными и полными. Редактирование текста выполняется по обычным правилам литературного языка, однако необходим и целый ряд дополнительных правил, касающихся должного стиля, формата, содержания документа и вытекающих из технической природы самого текста. Существуют несколько вопросов, на которые пишущий должен ответить перед началом работы над описанием, чтобы правильно определить нужные стиль, форму и содержание документа для достижения максимальной эффективности [1, 12, 29]:
5. Какая информация должна быть документирована? Существуют ли какие-либо ее части, на которые должно быть обращено особое внимание? Важно сконцентрироваться на целевом назначении документа. Забота о представлении мельчайших подробностей может привести к неудаче в обеспечении связности и удобочитаемости текста.
6. Для кого предназначен документ? Насколько отвлеченным может быть изложение материала? Должны быть определены потенциальные «читатели», а содержание документа необходимо привести в соответствие с их уровнем подготовки и требованиями.
7. Способы решения каких задач хочет знать пользователь? Указания в этой части должны быть ясными и полными. Необходимо заранее определить возможные ошибки пользователя и описать нужные действия по их исправлению.
8. Как будет использоваться описание? Например, учебное пособие и справочник существенно различаются по своему содержанию и должны быть по-разному организованы. Содержимое любого описания должно соответствовать его предполагаемому использованию.
9. Будут ли справочные материалы легкодоступными? Если нет, то описание должно быть исчерпывающим.
10. В каких условиях будет использоваться описание? Рабочие места различаются по свободной площади, поэтому размер и форма документов должны быть приспособлены к условиям, в которых они будут использоваться.
11. Сколько средств отпущено для выпуска документации? Сколько людей может быть привлечено и каков их уровень квалификации? Каков срок окончания работы над документацией? Тщательное планирование работы поможет уложиться в установленные временные и бюджетные ограничения.
12. Кто будет оценивать точность, полноту и ясность изложения? Человек, который разбирается в данной области и знаком с предполагаемым кругом пользователей, должен проверить документацию на наличие неточностей, пропусков, а также слов и фраз, которые могли бы внести путаницу.
13. Как документация будет обновляться и поддерживаться? Важно обеспечить механизм периодического пересмотра и внесения изменений в документацию после того, как она была проверена и начала использоваться. В пересмотренной редакции описания следует четко отметить абзацы, которые отличаются от предыдущего варианта. Одним из способов такой отметки изменений являются скобки на полях.