Вопросы документирования

16.10 Для обеспечения ясности изложения информации, содержащейся в ИЭД, необходимо соблюдать следующие принципы:

• важную значимую информацию давать в виде описательного текста;
• когда описательный текст приводится совместно с графикой, для сокращения текста необходимо:
  • устранить все междометия,
  • начинать предложения с переходных глаголов,
  • по мере возможности применять повелительное наклонение;
  • если нужно указать условие, предложение должно начинаться со слова «когда» (...когда напряжение питания стабилизируется...) и т.д.;
• не рекомендуется использовать сложноподчиненные и сложносочиненные предложения. Длинные параграфы или предложения необходимо разбивать на части;
• средняя длина предложения не должна превышать 20 слов. Средний абзац не должен превышать шесть предложений. Каждый абзац, по возможности, должен иметь заглавное или основное предложение, весь материал в абзаце должен быть по этой теме;
• за исключением особых обстоятельств, следует строить объяснение операций с максимальным использованием графических и мультимедийных возможностей;
• описательный текст следует давать в логической последовательности выполнения работы;
• описательный текст должен быть выдержан в единой терминологии, едином стиле и формате во всем ИЭД;
• при описании работы устройств, имеющих обозначения на их собственных панелях управления, их следует называть только по именам, указанным на панелях. При необходимости допускается использование дополнительного комментария;
• диалоги должны быть организованы таким образом, чтобы выполнение последующих действий было бы возможным только после ввода ответа пользователя. Информация должна быть представлена в базе данных ИЭД таким образом, чтобы после вывода сообщения на экран и получения ответа можно было бы произвести анализ ответа, определить потребности пользователя и предоставить ему необходимые данные.

[из 16.10 ГОСТ 2.610–2006]