А чтобы сделать качественно оформление документации по стандартам, надо про них знать и проверять документы при разработке.
В этой статье приведены самые распространенные ошибки в документах.
1. ОБЩИЕ ПОЛОЖЕНИЯ
Чтобы документ получился качественным, важно продумать и тщательно проработать его
ключевые аспекты:
− функция (назначение документа, его цели, целевая аудитория);
− структура;
− форма (оформление);
− содержание (смысловая составляющая).
Эти понятия – киты, на которых держится качество и эффективность любого технического
документа.
Ниже представлены типовые признаки некачественных документов в каждом из
аспектов. Представленный перечень признаков сформирован применительно к документам, разрабатываемым в MS Word, однако может быть полезен и при использовании других инструментов формирования технической документации. Некоторые признаки являются частными случаями в рамках каких-либо стандартов, однако перечень сформирован с учетом наиболее популярных серий
(ЕСКД, ЕСПД, КСАС).
2. ФУНКЦИЯ
документа.
2) Документ стремится охватить много различных (часто противоречивых) целей и/или
много различных сегментов целевой аудитории потенциальных читателей.
3) Документ в части структуры и контента не отвечает на типовые вопросы целевой
аудитории.
4) Документ не позволяет представителям целевой аудитории быстро находить
интересующую информацию.
3. СТРУКТУРА
подразделы, пункты и подпункты.
6) В документе отсутствует логическая последовательность изложения при переходе от
раздела к разделу.
7) Cодержимое разделов неуместно в контексте той цели, для которой эти разделы были
разработаны.
4. СОДЕРЖАНИЕ
9) Документ не согласуется с другими документами комплекта (например, по датам,
наименованиям подсистем, функций, компонентов).
10) Документ неверно адресован.
11) В тексте документа происходит явное или неявное переопределение терминов
(например, в верхней части документа под термином «Система» понимается некая
автоматизированная система, а далее вводится повторное определение, когда под
термином «Система» уже понимается СПО).
12) Применяются некорректные термины (например, отождествляются понятия
«автоматизированная система» и «программное обеспечение»).
13) Разные вещи называются одинаковыми терминами (например, клавиша на клавиатуре именуется кнопкой и возникает путаница между кнопками на клавиатуре и кнопками в графическом пользовательском интерфейсе).
14) Некорректно применяются (путаются при ссылках в тексте) следующие термины:
«раздел», «подраздел», «пункт», «подпункт».
15) Разделы, подразделы, пункты и подпункты получают названия путем копирования «в
лоб» строки требования ГОСТ, РД или ТЗ. При этом название структурного элемента
документа получается длинным в 3-5 строк.
16) Некорректно применяются термины (например, не разделяются или путаются понятия
«кнопка», «ссылка», «пиктограмма», «меню», «панель», «окно», «форма», «страница»,
«экран»).
17) В документе применяются сленговые термины, типа «иконка».
18) Много синонимов применяется для обозначения одной сущности (например, СПО,
программа, система, программное обеспечение, программный комплекс – и все в рамках
одного документа для одной сущности).
19) Содержимое раздела не соответствует его наименованию.
20) Перечень сокращений и обозначений содержит отсутствующие в документе сокращения и обозначения.
21) В документе применяется аббревиатура, не введенная в документе.
22) Формулировки не являются четкими и однозначными.
23) Методики проверок не четко соответствуют предъявляемым требованиям (актуально для ТУ, ПМИ, ПОЭ и подобных документов). Например, требование «изделие должно
соответствовать КД», а в методике описана проверка соответствия КД спецификации. Это ошибка.
24) Содержимое иллюстрации (рисунка, схемы, диаграммы) никак не соответствует
названию иллюстрации и/или вводному тексту, из которого дается ссылка. Частый
пример – это когда структурной схемой называют нечто, что по своей сути структурной
схемой не является.
25) При описании автоматизированной системы путаются понятия «функциональная
подсистема» («подсистема») и «компонент». Первое – является элементом
декомпозиции по функциональному признаку, а второе – элементом декомпозиции по
структурному признаку.
26) Используется математический термин «компонента» в технических документах
(например, по программному обеспечению) вместо корректного технического термина
«компонент» (определено ГОСТ ЕСПД).
27) Вместо нескольких простых предложений применяются «тяжелые» сложноподчиненные предложения с различными причастными/деепричастными оборотами.
28) От одного абзаца к другому меняется стиль изложения.
5. ОФОРМЛЕНИЕ
29) Форма документа не соответствует установленным требованиями (например, форма не соответствует необходимым стандартам ГОСТ, IEEE, требованиям технического задания или иным нормативным документам).
30) Оглавление не строится автоматически («ручное оглавление»).
31) При обновлении оглавления в нем «внезапно» появляются лишние надписи (это ошибки при форматировании абзацев – не вполне верно выбираются стили).
32) Присутствуют точки в заголовках разделов и подразделов (в конце текста заголовка).
33) Присутствуют множественные пробелы (двойные, тройные).
34) Выравнивание текста на странице выполнено с помощью пробелов и табуляций.
35) Использовано много разных шрифтов (более 3-х наименований шрифтов).
36) В таблицах не установлено запрещение переноса строки на следующую страницу.
37) В заголовках и ячейках таблицы не применяются стили (существенно затрудняет
последующее сопровождение документа).
38) В документе не выполняется (в уместных случаях) выравнивание текста по ширине.
39) Разные таблицы в документе не имеют выравнивания по левой и правой границе в
рамках документа.
40) Неуместно (некорректно) применяются знаки «дефис» и «тире».
41) Децимальный номер (обозначение документа) на титульном листе и в первом
колонтитуле – один, а в конце документа – другой (часто его забывают поменять в
нижних разделах при создании документа из шаблона).
42) Ссылки из текста на рисунки выглядят так: «показано на рисунке (Рисунок 1)», а не так: «показано на рисунке 1».
43) Обозначение документа, выпускаемого для автоматизированной системы, формируется без учета ГОСТ 34.201 и не соответствует требованиям стандарта. Аналогично для документов, выпускаемых в соответствии с требованиями ЕСКД, ЕСПД и др.
44) Отсутствует интервал между видимой строкой колонтитула (например, обозначение
документа или номер страницы) и основным текстом документа.
45) Нумерованные списки выполнены в редакторе (MS Word или иной) не как
нумерованные списки, а ручным внесением нумерации.
46) Весь документ выполнен единственным стилем (для MS Word это чаще всего стиль
«Обычный») и не используются соответствующие стили для разных типов контента.
47) В документе MS Word используется стиль «Обычный» хотя бы для одного типа
контента (это крайне не рекомендуется, поскольку стиль «Обычный» является
родительским стилем для множества наследованных от него пользовательских стилей).
48) Не применяются автоматические поля для нумерации страниц, общего числа страниц в документе и т.п. (а вместо этого все прописывается текстом вручную).
49) Не используются перекрестные ссылки (особенно при ссылках на номера разделов и подразделов).
50) Присутствуют «битые» перекрестные ссылки.
51) Не используются перекрестные ссылки для рисунков и таблиц, а вместо этого номера
рисунков и таблиц (как и ссылки на них) проставляются вручную.
52) В документ вставляется картинка, имеющая белый фон по границам (например, часть
окна браузера) и при этом рисунок не выделяется в рамку (вследствие этого в
напечатанном документе не видно, где заканчивается рисунок и начинается свободное
пространство страницы).
53) В документе присутствуют пустые строки (вместо того, чтобы необходимые отступы
делать путем настройки соответствующих стилей).
54) Перечисление однотипных сущностей выполняется внутри строки, а не маркированным или нумерованным списком с предшествующей титульной фразой.
55) В перечислениях, начинаемых со строчной буквы, ставится не «;» или «,» в конце
каждого элемента перечисления, а «.» или вообще ничего не ставится.
56) В перечислениях, начинаемых с заглавной буквы, ставится в конце каждого элемента
перечисления «;» или «,» вместо «.».
57) В документах одного типа (технический документ или организационный документ типа «исходящее письмо», «приказ» и т.п.) применяется разное форматирование от документа к документу.
58) На схемах и графиках отсутствуют ссылки и легенды, позволяющие понять схему без дополнительного сопроводительного текста.
59) На схемах много пересекающихся или сливающихся линий.
60) На схемах размер и тип шрифта разный у однотипных элементов.
61) На схемах однотипные элементы имеют случайные линейные размеры, которые никак
не соотносятся между собой.
62) При вставке схемы в текстовый документ в виде рисунка текст на схеме перестает быть читабельным (ввиду выбранного размера шрифта в соотношении с размером схемы).
63) Нарушаются базовые правила пунктуации (вводные слова, причастные и деепричастные обороты, однородные члены предложения, сложносочинённые и сложноподчинённые предложения, запятые перед союзами).
64) Нарушаются базовые правила орфографии (типовые ошибки с «-тся»/«ться», «в
течении»/«в течение», «также»/«так же» и т.п.).
65) Отсутствует единая стилистика оборотов в тексте документа. Примеры:
− в одном месте документа употребляется «нажать кнопку», в другом «нажать на
кнопку» (правильнее – первое);
− в одном месте «кликнуть мышью», а в другом «щелкнуть мышью»;
− в одном месте «в правом верхнем углу», а в другом «в верхнем правом углу»;
− и т.п.
66) При ссылке на стандарты (ГОСТ и др.) указаны некорректные обозначения (например,
пропускается буква «Р» для российских стандартов) или приводятся неполные/некорректные наименования документов. Чтобы не ошибаться в обозначении
или наименовании ГОСТ при упоминании их в документах, рекомендуется сверяться с
официальным наименованием и обозначением. Это можно делать на сайте
https://www.rst.gov.ru/portal/gost (в верхней части есть кнопка поиска, с помощью
которой можно найти точное обозначение и наименование интересующего стандарта).
67) «Оглавление» вместо «Содержание» и наоборот (в зависимости от типа документа и
стандарта, по которому выпускается документ).
68) В структурном элементе, где предполагается размещение подписи (например, на
титульном листе) не оставлено места (по вертикали) для размещения рукописной
подписи.
69) Наименование изделия на титульном листе, в основной надписи и при первом
упоминании в тексте – разные (частая ошибка).
70) Наименование изделия на титульном листе выполнено не заглавными буквами (кроме
документов ЕСПД) – это ошибка.
71) Перепутаны НКУ эксплуатации СВТ и НКУ испытаний СВТ. А это разные вещи.
Получить консультацию по документам
Оставьте заявку на обратный звонок или свяжитесь с нами:
Нажимая кнопку «Отправить», вы соглашаетесь с нашей Политикой конфиденциальности