ГОССТАНДАРТ РОССИИ - Информационная технология ПРОЦЕСС СОЗДАНИЯ ДОКУМЕНТАЦИИ ПОЛЬЗОВАТЕЛЯ ПРОГРАММНОГО СРЕДСТВА

4) библиографию специализированных словарей и стандартов;

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

d) каждое сокращение должно быть расшифровано при первом его появлении в тексте основной части документа;

e) каждый термин должен одинаково трактоваться в документе, диалоговой информации и системной библиотеке;

f) составные выражения (например, «ввод данных [data input]») должны иметь одно смысловое значение во всей документации;

g) составные выражения не должны содержать более трех слов;

h) одно и то же слово не должно использоваться для различных частей речи;

i) все специфические и специальные термины должны использоваться в соответствующем контексте;

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

k) следует избегать использования термина «биллион (billion)».

Примечание — Американский биллион (10 9) не совпадает с английским биллионом (10 12);

1) следует избегать использования термина «перевод (translation)», например при ссылке на перевод в формат файла, в смысловом значении, отличном от перевода с одного языка на другой. Вместо этого следует применять термин «преобразование (conversion)».

Следует использовать только общепринятые обозначения, которые должны быть расшифрованы в списке обозначений. Не должны применяться следующие обозначения:

a) американский символ «#» для фунта;

b) приподнятая точка () для операции умножения.

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

а) who (кто), that (который), which (какой);

b) only (только), merely (приблизительно), just (едва), mainly (в основном), simply (просто);

с) while (пока);

d) so (таким образом);

e) as (как);

f) can (иметь возможность), may (мочь);

g) since (так как);

h) when (когда), if (если);

i) alternate (дополнительный), alternative (альтернативный).

Должны быть учтены следующие вопросы синтаксиса:

a) предложения не должны быть слишком длинными;

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

c) пункты, содержащие определенные ограничения, и пункты без ограничений должны быть представлены раздельно.

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

Необходимо учитывать следующие физические факторы:

a) сокращения нецелесообразно использовать только для экономии места;

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

c) следует использовать стандартные графические инструментальные средства (пакеты) и избегать применения вклеек;

d) избегать внесения поясняющего текста в рисунки;

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

f) по возможности вместо словесного пояснения использовать графические изображения.

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

a) при наличии обратной связи с разработчиками программных средств следует обеспечить выделение диалоговой информации (текстов и сообщений) из логики программы;

b) каждый блок текста или сообщение должны иметь индивидуальное идентификационное обозначение

с указанием соответствующей классификационной группы данного текста или сообщения;

c) конкретное программное средство не должно ориентироваться на длину, формат или расположение незащищенных экранных полей ввода-вывода (input and output fields);

d) для каждого понятия следует использовать отдельное сообщение. Сообщения не должны быть надуманными;

e) переменные в сообщении должны содержать только непереводимую информацию, например ключевые слова и коды возврата;

f) из предложений не следует исключать предлоги в целях экономии места.

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

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

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

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

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

e) следует осторожно использовать иронические выражения;

f) необходимо избегать использования сленговых, жаргонных и простонародных выражений;

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

h) не следует выражать даты только в числовом виде. Месяц всегда должен быть написан полностью (например, 28 июля 1991);

i) обычно следует использовать двумерные представления, если международные соглашения не требуют иного (например, для автошин, водопроводов, гвоздей и фотопленки);

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

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

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

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

По общей оценке требуется от 3 до 5 ч для создания и корректировки типового графического материала, используемого в программной документации (исключая экранные распечатки).