Комментарии 34
Неаккуратно
Не придирайтесь)
В целом все очень по уму написано!
Единственное, на что могу обратить внимание «нумерация приложений» согласно п. 6.3.5 из ГОСТ Р 2.105-2019 (Единая система конструкторской документации. Общие требования к текстовым документам):
6.3.5 Элемент «Приложение» обозначают прописными буквами русского алфавита, начиная с А, за исключением букв Ё, З, Й, О, Ч, Ь, Ы, Ъ.
Допускается обозначение буквами латинского алфавита, за исключением букв I и O.
В случае полного использования букв русского и латинского алфавитов допускается обозначать приложения арабскими цифрами.
Если в документе одно приложение, оно обозначается «Приложение А».
В самом ГОСТ Р 2.105-2019 приложения обозначаются русскими буквами.
ХХХХ_YYYYY_V._._.ГГГГ.ММ.ДД, где:
ГГГГ.ММ.ДД – дата редактирования файла.
Дату редактирования файла лучше брать из данных файловой системы, а не хранить в имени
дата в файловой системе может измениться, например, при копировании файлов.
Спасибо, да если вы не используете ворд так и есть. Но, при использовании ворда - эта система работает очень ненадежно)))
Вы все пишите документацию на программные средства в Word-е? Неужели чего-то более дельного нет? Вставлять GUI для каждой версии продукта (особенно после проказников-дизайнеров) имхо должно быть мучительно.
Большинство заказчиков(ГОС или около ГОС), как правило, заявляют формат предоставления документации как - .doc/.docx, и это требование нельзя изменить/убрать из ТЗ ¯\_(ツ)_/¯
Выгрузку в .doc ни одна система не осуществляет? Не верю! ¯\_(ツ)_/¯
Выгрузку в .doc ни одна система не осуществляет?
Например в техническом задании от ЦентроБанка РФ всегда идет приложение с описанием, как должны быть оформлены предоставляемые документы. В котором прописано что документы предоставляются в doc(x) и на 6 страницах перечисление каким размером шрифта, с каким отступом и т.п. должны быть каждая надпись (т.е. заголовки всех уровней, основной текст, подписи к рисункам и таблицам).
Может и осуществляют. Боюсь на вы не сможете получить на выходе документ Word, котором все параметры совпадут с пожеланиями данного Заказчика…
PS В нашем случае документация не на программные средства.
Конечно можно генерировать доки, пример в Polarion. Форму документа тоже можно настраивать под заказчика.
Слушайте, ну если бы выгрузка была бы столь проста и соответствовала требованиям оформления, то конечно. Но когда Заказчику мало получить док в ворде, а запрашивают еще и версию с правками, то тут уже...
Мы придерживаемся требований от Заказчика)))
Интересно, почему в любой иностранной документации ещё присутствует список изменений версий документа? В правилах хорошего тона есть ещё место для улучшения?
В правилах хорошего тона есть ещё место для улучшения?
В принципе данная статья это перевод на человеческий язык официозного документа ГОСТ Р 2.105-2019.
почему в любой иностранной документации ещё присутствует список изменений версий документа?
В п. 5.1.8 вышеуказанного ГОСТ Р 2.105-2019 есть такие слова
5.1.8 В ТД включают лист регистрации изменений в соответствии с ГОСТ 2.503 и ГОСТ Р 21.1101. Лист регистрации изменений допускается оформлять одновременно с внесением изменений.
Листы регистрации изменений в ГОСТ 2.503-2013 (Единая система конструкторской документации. Правила внесения изменений) описаны в Приложении В.
В ГОСТ Р 21.101-2020 (Система проектной документации для строительства. Основные требования к проектной и рабочей документации) описаны в Приложении Н.
На мой взгляд улучшать можно бесконечно
Если честно, то мы крайне редко ведём этот лист. В лучшем случае просто вставляем пустой лист с соответствующей формой)
В своих документах я предпочитаю целесообразность.
Абсолютно с вами согласен! В конторе где я работал пару лет назад к этому листу было особенное отношение. К текстовому документу из 10 листов, прилагались листы регистрации изменений бывало до 3-5. В формате типа
п.1.1 исправлена опечатка в слове "коммутатор"; п. 1.2 заменена гарнитура шрифта с Arial на Ghost type B; etc
"нельзя использовать технического писателя в качестве оформителя". Это значит надо отдельного сотрудника нанимать?
Версию файла лучше за датой ставить, т.к. за день может быть более одной версии.
Список того, что недопускается применять в тексте документа в первую очередь определяется "языком" на котором происходит общение с бизнесом. И если, условный "чекбокс" всем понятен, то лучше использовать его чем какой-нибудь "крыжик".
В остальном всё по делу. Если работа ведётся в Ворде, то нумерацию страниц, таблиц и рисунков нужно делать автоматической и вставлять интерактивные ссылки. В таком случае их просто обновлять при вставке содержимого в середину документа. Жаль чего-то подобного нет для списков и таблиц, когда нужно сослаться на конкретный пункт или строку.
Делать документацию в docx - это мука. И дело не столько в том, что MS Word не удобен (на самом деле, он божественен), сколько в том, что сопровождает разработку документации. Здесь и часто меняющиеся шаблоны, и постоянно съезжающие нумерации всего и вся, и две-три параллельные версии одного и того же документа и частые "откаты" изменений, сборка всех правок в один "финальный" документ...
Правильно заметили, что нужно хранить документацию в какой-нибудь системе контроля версий. Я бы так вообще переходил везде на markdown, хранил бы разные разделы документа в разных файлах с разным уровнем доступа, применял динамические ссылки на таблицы/рисунки/схемы и собирал бы финальную версию документа (для подписи) скриптом.
Неужели еще нет какой-нибудь информационной системы для ведения документации со встроенным контролем версий?
сборка всех правок в один "финальный" документ...
Это реально адЪ!
Здесь и часто меняющиеся шаблоны
А это зачем?
Я бы так вообще переходил везде на markdown
Я бы тоже хотел, но у нас в документации встречается более 54 гендеров 270 различных стилей!!! Боюсь в md такое стилевое разнообразие будет не будет невозможно…
Правила хорошего тона при оформлении технической документации