Привет, хабр! Я технический писатель в компании Bimeister.
Наша компания занимается разработкой программного обеспечения для автоматизации крупных производств. Вместе с тем мы разрабатываем большой объем технической и проектной документации. Так получилось, что Заказчики наших продуктов стремятся к соблюдению требований государственных стандартов (далее — ГОСТ), поэтому всю отчетную документацию мы пишем в соответствии со стандартами.
Кажется, что все достаточно просто — пишешь по ГОСТ, и все остаются довольны. Но, как показывает практика, не всё так однозначно как должно быть в документах уровня ГОСТ, и у каждого Заказчика есть свое видение относительно требований стандартов, под которое нам приходится подстраиваться.
Требования Заказчика будут проходить красной нитью по всей статье, поэтому сразу приведу цитату, которая успокаивает мне нервы в такие моменты:
«Ты можешь быть бесконечно прав, но какой в этом толк, если твой Заказчик плачет?» |
В этой статье я расскажу об оформлении титульной части документов, а также раздела с терминами и сокращениями. А именно о том, к какому оформлению мы пришли совместно с нашим специалистом по нормоконтролю (да, у нас он есть!) путем многочисленных проб и ошибок.
Титульная часть
Согласно ГОСТ, титульная часть состоит из титульного листа и листа утверждения.
Лист утверждения и согласование документа
Лист утверждения используется, если на титульном листе по какой-либо причине нельзя размещать подписи. У нас в компании нет практики использования листа утверждения, необходимые подписи выносят на титульный лист, а также на листы согласования, которые появились по требованию Заказчиков. Форма листов согласования не стандартизована, была определена и предложена Заказчиком. Листы согласования мы не нумеруем и в общее количество страниц не включаем. Таким образом, есть возможность в электронной версии документа разместить листы согласования как в начале документа, так и в конце. А при хранении бумажных копий документов листы согласования вообще могут храниться отдельно.
Про оформление листа утверждения можно почитать в ГОСТ Р 2.105-2019.
Титульный лист
Титульный лист — это обязательный элемент документа.
На титульном листе мы указываем:
грифы утверждения (при необходимости) — в верхней части листа: слева — Заказчик, справа — Разработчик;
групповые заголовки: наименование проекта — не во всех случаях (по согласованию с Заказчиком), наименование системы;
групповой подзаголовок: наименование модуля системы;
вид документации (например ー «Эксплуатационная документация») — при необходимости;
название документа;
год разработки документа — размещаем в нижнем колонтитуле.
Заголовки на титульном листе разделяем пустой строкой, исходя из логики: для всех предложений, входящих в полное название документа и в тексте разделенных точкой, на титульном листе точки не ставим, а заменяем их одной пустой строкой (или одной высотой шрифта, если говорить в формулировках ГОСТ).
Вот один из примеров нашего обычного титульного листа.
Что еще добавляем на титульный лист (по согласованию с Заказчиком или при необходимости):
полное и сокращенное наименование организации-разработчика — размещаем в верхнем колонтитуле с расстоянием от края до верхнего колонтитула равном 2 см;
грифы согласования: слева — Заказчик, справа — Разработчик;
город разработки, как и год утверждения, размещаем в нижнем колонтитуле.
Планируем вносить шифр документа (обозначение, уникальный код).
Да, недавно нам пришлось задуматься об учете документации, но мы пока решаем, как его лучше вести, какую систему организовать? Поделитесь опытом в комментариях: как ведется учет документации в вашей организации, как налажена система регистрации документов? Возможно это какая-то картотека: электронная (преимущественно) или бумажная (чего не хотелось бы)...?
Что хотелось бы исправить: возможно кто-то заметил, что на титульном листе в нашем примере место для простановки даты в грифах определено тремя сплошными линиями через некоторый интервал. То есть предполагается, что вручную будет вписано число, месяц прописью, год, и только ТАК!
Как мы не просили Заказчика оставить одну черту, тем самым не ограничивая подписанта в выборе формата простановки даты, к сожалению, мы не были услышаны. Максимум в чем удалось прийти к консенсусу ー это убрали кавычки там, где предполагается число. Во-первых, формат записи даты определен ГОСТ Р 7.0.97-2016, при этом, ни в одном из двух способов нет кавычек. Во-вторых, наличие кавычек в дате возвращает нас в прошлое, во времена набивания текста на печатных машинках, когда место для простановки в дальнейшем числа вручную обозначали кавычками.
Основы оформления титульного листа изложены в стандартах:
ГОСТ 19.104-78;
ГОСТ Р 2.105-2019.
Термины, определения, сокращения и обозначения
Кажется, что это одни из самых элементарных разделов документа, но, если разбираться, то по их оформлению возникает очень много вопросов.
Оформление разделов описано в ГОСТ Р 2.105-2019, который в свою очередь ссылается на ГОСТ 7.32-2017.
Где располагать?
Мы располагаем в начале документа первым разделом, в составе которого два подраздела: «Термины и определения» и «Обозначения и сокращения» либо двумя соответствующими самостоятельными разделами. Несмотря на то, что ГОСТ не запрещает выносить термины и сокращения в приложения, мы считаем, что удобнее для пользователя вначале ознакомиться с принятыми в документе сокращениями и примененными терминами, а уже потом — «слегка осведомленным» — пройтись по тексту.
Я лично, например, всегда сначала изучаю термины и сокращения документа, чтобы потом реже возвращаться к этому разделу.
Нужно ли нумеровать раздел?
Мы нумеруем, так как эти разделы являются частью основного текста. Но при оформлении документов вида «Техническое задание» располагаем перечни терминов и сокращений в конце документа и без нумерации, в той последовательности, как предлагает ГОСТ 19.106-78.
Как называть?
Мы называем раздел в зависимости от его содержания. Как я писала выше, стандарты позволяют объединять разделы с терминами и сокращениями, поэтому название выстраивается одним из следующих вариантов:
«Термины, определения и сокращения» — если в тексте нет обозначений;
«Термины, определения, обозначения» — если в тексте нет сокращений (но такого на нашей практике еще не встречалось);
«Термины, определения, обозначения и сокращения» — если в тексте есть и обозначения и сокращения.
Здесь лично у меня возникает вопрос: почему для терминов в заголовке раздела есть определения, но для сокращений нет расшифровок? По логике раздел нужно называть либо «Термины и сокращения», либо «Термины и определения, сокращения и расшифровки». Наш специалист по нормоконтролю рассуждает так: терминологическая статья состоит из термина и определения, причем определения желательно использовать стандартизованные, не придумывать самостоятельно, а применять существующие. Вероятно поэтому в документе важно понять, какое определение вы применили к термину с учетом специфики изложенного материала. Что же касается сокращений, то в документе мы их принимаем (вводим) на свое усмотрение и, по большей части, для удобства использования в тексте длинных часто встречающихся словосочетаний.
К обозначениям обычно относим: условные обозначения (например — EN — что означает раскладку клавиатуры на английском языке), символы, единицы физических величин.
Оформлять списком или таблицей?
Зависит от требований Заказчика. Чаще всего мы оформляем в виде списка, при этом используем таблицу с невидимыми границами из трех граф: в первой — термин, во второй — знак тире (это самая узкая графа, около 4 мм), в третьей — определение. У таблицы следует установить поля равные нулю, ширину таблицы — по ширине окна и к тексту применить оформление основного текста, но без абзацного отступа.
В случае оформления терминов в виде таблицы, применяем все правила оформления таблиц, изложенные в ГОСТ Р 2.105-2019.
Ни в списке, ни в таблице не используем знаки препинания в конце |
Для таблицы или списка обязательно используем вводную фразу:
для терминов:
«В настоящем документе применены следующие термины с соответствующими определениями:» ー в случае оформления в виде списка;
«В настоящем документе применены термины с соответствующими определениями, приведенные в таблице 1.» ー в случае оформления в виде таблицы;
для сокращений:
«В настоящем документе приняты следующие сокращения (и обозначения):» ー в случае оформления в виде списка;
«В настоящем документе приняты сокращения (и обозначения), приведенные в таблице 2.» ー в случае оформления в виде таблицы.
Обратите внимание, что термины мы применяем, потому что, по идее, термины мы не выдумываем, а используем в тексте уже существующие, а вот сокращения можем вводить какие хочется, поэтому их принимаем.
В каком порядке располагать?
ГОСТ предлагает располагать термины, сокращения и обозначения несколькими вариантами:
«от общего — к частному» или от «определяющего — к определяемому»;
в порядке употребления в тексте;
по алфавиту, если терминов или сокращений больше 20 (хотя ГОСТ 19.106-78 рассматривает только алфавитный порядок).
Мы всегда располагаем по алфавиту, даже если у нас их меньшее количество, чем регламентирует ГОСТ. Так просто привычнее.
Если в тексте есть еще и англоязычные термины, то располагаем сначала их в алфавитном порядке, затем русскоязычные.
С сокращениями и обозначениями (редко встречаются в наших документах) используем следующий порядок:
обозначения;
сокращения на иностранном языке;
сокращения на русском языке.
Что именно вносить?
В раздел включаем только те термины и сокращения, которые использованы в тексте.
Термины
В перечень терминов стоит выносить те узкоспециализированные понятия, которым необходимо дать определение с целью однозначности их понимания, всеми читателями.
Например ー «Пользователь» — это просто тот, кто пользуется описанной системой, или это какой-то конкретный специалист со стороны Заказчика? Именно в подобном случае стоит дать объяснение читателю.
Точно также, для однозначного понимания текста документа, к перечню терминов мы добавляем определения частного характера, такие как: «Заказчик», «Исполнитель», «Система».
Сокращения
В перечень включают все сокращения, которые вводятся по тексту документа, за исключением:
общепринятых сокращений слов и словосочетаний (т. д., т. п., др. и пр.);
сокращений адресообразующих элементов (ул., д., обл. и т. д.);
единиц физических величин (см, м, кг);
аббревиатур форм собственности (АО, ООО, ПАО и пр.);
сокращений наименований федеральных органов исполнительной власти (МВД, МЧС и т. д.);
общепринятых сокращений в официально-деловой речи (РФ, СНГ и т. д.).
В ГОСТ указано, что если сокращений в тексте менее трех, то их нужно пояснять в тексте. Мы этому правилу не следуем, а всегда оформляем подраздел, но у нас и крайне редко бывает ситуация, когда сокращений меньше.
Почему нарушаем? По аналогии с содержанием. Его тоже нужно составлять только в том случае, если в документе больше 24 страниц. Требования ГОСТ зачастую ориентированы на бумажный формат, а сейчас в приоритете удобная навигация в электронной версии документа.
Обозначения
Обозначения можно расшифровывать сразу в тексте примечанием или сноской, а можно вынести в перечень. В наших документах обозначения в большинстве случаев используются при написании формул, и поясняем мы их здесь же ー сразу после формулы, что не противоречит требованиям стандартов.
Смысл данной статьи был показать вам, что стандарты хоть и ограничивают нас в некоторых моментах, но существуют «лазейки», которые позволяют удовлетворить Заказчика, при этом не лишившись здравого смысла и не нарушив требования ГОСТ. Вместе с тем документация остается удобна и для разработчика, и для того, кто будет использовать ее в работе.