difi123 Jul 11 2023 at 12:11

Правила хорошего тона при оформлении технической документации

Easy

5 min

10K

Bimeister corporate blogTechnical Writing*

+13

Comments 34

Dounar Jul 11 2023 at 12:23

Jianke Jul 12 2023 at 13:06

lol

Автор, поучающий как надо, явно не умеет использовать tab для выравнивания отступов.

Если бы он умел, то всё выравнялось бы как надо

PS но, хоть титул он догадался разметить почти правильно:

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

difi123 Jul 18 2023 at 13:34

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

Jianke Jul 18 2023 at 13:45

При автоматической нумерации страниц достаточно одного таба, чтобы цифры в оглавлении встали прямо по линейке.

difi123 Jul 20 2023 at 10:36

Возможно, вы не заметили. Но! Есть логика того, что заголовки и подзаголовки находятся на разном расстоянии.

Surrogate Jul 11 2023 at 12:40

Неаккуратно

Не придирайтесь)

В целом все очень по уму написано!

Единственное, на что могу обратить внимание «нумерация приложений» согласно п. 6.3.5 из ГОСТ Р 2.105-2019 (Единая система конструкторской документации. Общие требования к текстовым документам):

6.3.5 Элемент «Приложение» обозначают прописными буквами русского алфавита, начиная с А, за исключением букв Ё, З, Й, О, Ч, Ь, Ы, Ъ.
Допускается обозначение буквами латинского алфавита, за исключением букв I и O.
В случае полного использования букв русского и латинского алфавитов допускается обозначать приложения арабскими цифрами.
Если в документе одно приложение, оно обозначается «Приложение А».

В самом ГОСТ Р 2.105-2019 приложения обозначаются русскими буквами.

difi123 Jul 18 2023 at 13:39

не забывайте про ИТ-ые ГОСТ.

ГОСТ 19.104

Surrogate Jul 18 2023 at 14:06

не забывайте про ИТ-ые ГОСТ

Я далек от этого вашего ИТ :)

Видел у вас упоминание ГОСТ Р 2.105, думал что нумерация "цифровая" потому что ее можно реализовать стилями заголовков без лишних приседаний…

belch84 Jul 11 2023 at 12:49

ХХХХ_YYYYY_V._._.ГГГГ.ММ.ДД, где:
ГГГГ.ММ.ДД – дата редактирования файла.

Дату редактирования файла лучше брать из данных файловой системы, а не хранить в имени

alexxisr Jul 11 2023 at 13:20

дата в файловой системе может измениться, например, при копировании файлов.

Surrogate Jul 11 2023 at 13:33

Может измениться, когда пользователь открыл документ «на посмотреть». При этом было открыто много документов и он по ошибке закрывая файл, нажмет «Сохранить изменения».

dmitryvolochaev Jul 11 2023 at 15:33

Надо хранить документы в системе контроля версий. Туда ничего не сохранится случайно. И даты там тоже есть

difi123 Jul 18 2023 at 13:38

какими системами для контроля версий вы пользуетесь?

dmitryvolochaev Jul 19 2023 at 20:18

Я имею ввиду те же системы, что и для кода. Git, например

belch84 Jul 11 2023 at 14:06

С другой стороны, можно забыть её изменить в названии при редактировании

difi123 Jul 18 2023 at 13:37

Спасибо, да если вы не используете ворд так и есть. Но, при использовании ворда - эта система работает очень ненадежно)))

little-brother Jul 11 2023 at 13:52

Вы все пишите документацию на программные средства в Word-е? Неужели чего-то более дельного нет? Вставлять GUI для каждой версии продукта (особенно после проказников-дизайнеров) имхо должно быть мучительно.

voody77 Jul 11 2023 at 14:44

Большинство заказчиков(ГОС или около ГОС), как правило, заявляют формат предоставления документации как - .doc/.docx, и это требование нельзя изменить/убрать из ТЗ ¯\_(ツ)_/¯

little-brother Jul 11 2023 at 15:08

Выгрузку в .doc ни одна система не осуществляет? Не верю! ¯\_(ツ)_/¯

Surrogate Jul 11 2023 at 17:45

Выгрузку в .doc ни одна система не осуществляет?

Например в техническом задании от ЦентроБанка РФ всегда идет приложение с описанием, как должны быть оформлены предоставляемые документы. В котором прописано что документы предоставляются в doc(x) и на 6 страницах перечисление каким размером шрифта, с каким отступом и т.п. должны быть каждая надпись (т.е. заголовки всех уровней, основной текст, подписи к рисункам и таблицам).

Может и осуществляют. Боюсь на вы не сможете получить на выходе документ Word, котором все параметры совпадут с пожеланиями данного Заказчика…

PS В нашем случае документация не на программные средства.

iggr63 Jul 11 2023 at 22:41

Конечно можно генерировать доки, пример в Polarion. Форму документа тоже можно настраивать под заказчика.

difi123 Jul 18 2023 at 13:42

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

difi123 Jul 18 2023 at 13:40

Мы придерживаемся требований от Заказчика)))

timsiling Jul 12 2023 at 06:54

Интересно, почему в любой иностранной документации ещё присутствует список изменений версий документа? В правилах хорошего тона есть ещё место для улучшения?

Surrogate Jul 12 2023 at 09:43

В правилах хорошего тона есть ещё место для улучшения?

В принципе данная статья это перевод на человеческий язык официозного документа ГОСТ Р 2.105-2019.

почему в любой иностранной документации ещё присутствует список изменений версий документа?

В п. 5.1.8 вышеуказанного ГОСТ Р 2.105-2019 есть такие слова

5.1.8 В ТД включают лист регистрации изменений в соответствии с ГОСТ 2.503 и ГОСТ Р 21.1101. Лист регистрации изменений допускается оформлять одновременно с внесением изменений.

Листы регистрации изменений в ГОСТ 2.503-2013 (Единая система конструкторской документации. Правила внесения изменений) описаны в Приложении В.

В ГОСТ Р 21.101-2020 (Система проектной документации для строительства. Основные требования к проектной и рабочей документации) описаны в Приложении Н.

timsiling Jul 12 2023 at 09:48

Спасибо! Прошу прощения, если написал немного в резком тоне. Увы, писал на бегу.

В целом, слово "официозный" хорошо характеризует документ. В своих документах я предпочитаю целесообразность.

difi123 Jul 18 2023 at 13:44

На мой взгляд улучшать можно бесконечно

Surrogate Jul 12 2023 at 10:22

Если честно, то мы крайне редко ведём этот лист. В лучшем случае просто вставляем пустой лист с соответствующей формой)

В своих документах я предпочитаю целесообразность.

Абсолютно с вами согласен! В конторе где я работал пару лет назад к этому листу было особенное отношение. К текстовому документу из 10 листов, прилагались листы регистрации изменений бывало до 3-5. В формате типа

п.1.1 исправлена опечатка в слове "коммутатор"; п. 1.2 заменена гарнитура шрифта с Arial на Ghost type B; etc

rever50 Jul 12 2023 at 10:28

"нельзя использовать технического писателя в качестве оформителя". Это значит надо отдельного сотрудника нанимать?

difi123 Jul 18 2023 at 13:46

Использовать техписа для оформления документов - это дорого. Оформитель стоит дешевле

z250227725 Jul 13 2023 at 08:40

Версию файла лучше за датой ставить, т.к. за день может быть более одной версии.
Список того, что недопускается применять в тексте документа в первую очередь определяется "языком" на котором происходит общение с бизнесом. И если, условный "чекбокс" всем понятен, то лучше использовать его чем какой-нибудь "крыжик".
В остальном всё по делу. Если работа ведётся в Ворде, то нумерацию страниц, таблиц и рисунков нужно делать автоматической и вставлять интерактивные ссылки. В таком случае их просто обновлять при вставке содержимого в середину документа. Жаль чего-то подобного нет для списков и таблиц, когда нужно сослаться на конкретный пункт или строку.

Surrogate Jul 13 2023 at 10:02

В самом "MS Word из коробки" всего этого нет. Но при желании и наличии свободного времени можно это запилить с помощью встроенного языка программирования Visual Basic for Application (VBA), ну или другого стороннего языка...

Shavadrius Jul 13 2023 at 08:42

Делать документацию в docx - это мука. И дело не столько в том, что MS Word не удобен (на самом деле, он божественен), сколько в том, что сопровождает разработку документации. Здесь и часто меняющиеся шаблоны, и постоянно съезжающие нумерации всего и вся, и две-три параллельные версии одного и того же документа и частые "откаты" изменений, сборка всех правок в один "финальный" документ...

Правильно заметили, что нужно хранить документацию в какой-нибудь системе контроля версий. Я бы так вообще переходил везде на markdown, хранил бы разные разделы документа в разных файлах с разным уровнем доступа, применял динамические ссылки на таблицы/рисунки/схемы и собирал бы финальную версию документа (для подписи) скриптом.

Неужели еще нет какой-нибудь информационной системы для ведения документации со встроенным контролем версий?

Surrogate Jul 13 2023 at 10:41

сборка всех правок в один "финальный" документ...

Это реально адЪ!

Здесь и часто меняющиеся шаблоны

А это зачем?

Я бы так вообще переходил везде на markdown

Я бы тоже хотел, но у нас в документации встречается более ~~54 гендеров~~ 270 различных стилей!!! Боюсь в md такое стилевое разнообразие будет не будет невозможно…