Подготовка технической документации *

Привет, Хабр! В 2020 году компания решила вывести на рынок линейку продуктов Platform V. Для них нужна была документация, которая на тот момент велась в Confluence. Нам предстояло проделать сложную и дорогую работу: собрать документы на нужные версии, привести тексты к единому стилю и терминологии, оформить как комплект документации от поставщика ПО. Расскажу, какие инструменты мы в СберТехе использовали, почему перешли от документирования в Confluence нa Docs-as-a-Code и создали инструмент Platform V GetDocs, который помогает эффективно писать документацию.

"Коллеги, пришлите сроки!" - повторял джун-аналитик в течение месяца...

Ситуация: 3 месяца назад, я, начинающий системный аналитик, пришла в монстрически крупную компанию. С первого дня меня кинули в рабочие задачи: напиши письма, протоколы, уточни сроки, откорректируй JSON-ку, попробуй написать требования... Задачи довольно простые, НО я понятия не имела, почему некоторые коллеги из смежных систем отвечают на мои письма за 1 день, в то время как другие просто игнорируют письма неделями.

По рабочим вопросам, я применяю DeepL для перевода технической документации, так как необходимое качество «подстрочника» он обеспечивает и ускоряет работу над однотипными текстами, которые после остается только вычитать и поправить явные ляпы в оборотах и терминологии. Но захотелось посмотреть, а что можно применить взамен, бесплатно, offline и в связке с VS Code, особенно учитывая намеки авторов переводчика скоро прикрыть «халяву» с бесплатным AI Writer.

У нас во «Фланте» инженеры работают еще и с технической документацией. При этом многие термины, например, относящиеся к Kubernetes, пишут по-разному: кто-то использует сленг, кто-то — латиницу, а кто-то — кириллицу. Чтобы навести порядок в терминологии, а заодно и исправлять опечатки, мы решили создать спелл-чекера и автоматизировать проверку орфографии.

В этой статье мы расскажем, как проходила настройка спелл-чекера для сайта werf, сгенерированного внутри Docker-контейнера, и что получилось в итоге. Пройдёмся по всем этапам создания этого инструмента, а также разберём проблемы, которые могут усложнить настройку автоматической проверки орфографии.

Мировая статистика говорит, что английским владеет примерно 1,4 миллиарда человек, но носителей среди них всего 380 миллионов. То есть статистически семь из десяти читателей англоязычной документации — не носители языка.

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

Документация должна быть написана так, чтобы даже тот, кто плохо знает язык, мог ей воспользоваться.

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

Всем привет!

Меня зовут Александр Денисов. Я работаю в компании Naumen и отвечаю за документирование и локализацию программного продукта Naumen Contact Center (NCC).

В этой статье я расскажу о том, как у нас был автоматизирован процесс перевода документации с помощью нейродвижков без использования CAT-систем и каких-либо других инструментов перевода.

Участие России в ВТО потребовало стандартизации терминов и определений, для: «предупреждения действий, вводящих в заблуждение приобретателей, в том числе потребителей» (ст. 6, 46 184-ФЗ). Двухуровневая система разделения технических регламентов и ГОСТов, обусловленная их обязательным и добровольным характером, согласно статье 46 184-ФЗ, преобразуется в одноуровневую. В современном российском обществе, когда правила статьи 46 указа 184-ФЗ “О стандартизации” и ГОСТы являются необходимыми к выполнению, появляется потребность в применении и сравнении тысяч терминов. В целях упрощения работы со множеством терминов  был создан этот словарь.

В действующем 184-ФЗ “О техническом регулировании”, ратифицированный Россией при присоединении к ВТО, требуется, чтобы любая продукция была безопасна для: «предупреждения действий, вводящих в заблуждение приобретателей, в том числе потребителей» (ст. 6, 46 184-ФЗ). Двухступенчатая система разделения техрегламентов и ГОСТов, согласно статье 46 184-ФЗ, становится в России однступенчаиой. Для реализации этих требований вводятся технические регламенты, которых прогнозируется около 2000. В технических проектах термины являются юридически основными условиями. Создание словаря - облегчит выбор необходимых  терминов.

Участие в ВТО экономики России потребовало стандартизации терминов и определений, для: «предупреждения действий, вводящих в заблуждение приобретателей, в том числе потребителей» (ст. 6, 46 184-ФЗ). Двухуровневая система разделения технических регламентов и ГОСТов, обусловленная их обязательным и добровольным характером, согласно статье 46 184-ФЗ, преобразуется в современном правовом обществе в одноуровневую. Преобразование поставило задачу по созданию описаний, контрактов на поставку и интерпретации определений используемых терминов. Словарь включает в себя тысячи определений для более эффективного решения задач в сфере IT-отрасли.

При составлении контрактов, технических заданий, проектов термины становятся юридически значимыми определяющими условиями. В текущих условиях, когда требования ст. 46 184-ФЗ «О техническом регулировании», ГОСТы являются уже не добровольной, а обязательной нормой. Возникает необходимость использовать и сопоставлять тысячи терминов. Этот словарь был создан для того, чтобы упростить работу с указанными понятиями.

Участие России в ВТО потребовало стандартизации терминов и определений, для: «предупреждения действий, вводящих в заблуждение приобретателей, в том числе потребителей» (ст. 6, 46 184-ФЗ). Двухступенчатая система разделения на обязательные технические регламенты и добровольные государственные стандарты (ГОСТы) становится одноступенчатой после учета норм статьи 46 184-ФЗ. В современной экономике, когда положения статьи 46 184-ФЗ и ГОСТы становятся обязательными к исполнению, возникает потребность в использовании и сравнении тысяч терминов. Упростить работу с этими понятиями в сфере IT-отрасли, создан данный глоссарий

Закон №184-ФЗ “О техническом регулировании”, принятый при вступлении России во Всемирную торговую организацию, требует, чтобы вся продукция была безопасной и не вводила покупателей в заблуждение. Для этого создаются технические регламенты: сейчас их 54, но ожидается, что потребуется еще около 2 тысяч. ГОСТы, СНИПы и СанПины, которые действовали в СССР, остались и сейчас, но согласно №184-ФЗ применяются они только на добровольной основе. Если товар относится к вопросам безопасности и достоверности, по закону нужно использовать актуальные ГОСТы, СНИпы и СанПины - это указано в статье 46 №184-ФЗ и в гражданском кодексе (статья 309). К примеру, если вы назовете “рубильник” “выключателем”, вас могут оштрафовать за нарушение № 184-ФЗ - статью 14.4 кодекса об административных нарушениях. Словарь, который мы предлагаем, поможет вам выбирать корректные термины и избегать ошибок.

Членство России в ВТО потребовало стандартизации терминов и определений, для: «предупреждения действий, вводящих в заблуждение приобретателей, в том числе потребителей» (ст. 6, 46 184-ФЗ). Двухуровневая система разделения технических регламентов и ГОСТов, обусловленная их обязательным и добровольным характером, согласно статье 46 184-ФЗ, преобразуется в одноуровневую. Преобразование поставило задачу по созданию описаний, контрактов на поставку и интерпретации определений используемых терминов. Словарь включает в себя десятки тысяч определений для более эффективного решения задач в сфере IT-отрасли.

При разработке контрактов, технических заданий и проектов, термины приобретают статус юридически важных, определяющих положений. В текущих условиях, когда требования ст. 46 184-ФЗ «О техническом регулировании», ГОСТы являются уже не добровольной, а обязательной нормой. Необходимо использовать и сравнивать тысячи терминов. Для облегчения работы с этими понятиями и создан этот словарь.

Участие в ВТО поставило Россию перед задачей стандартизации терминов и определений, для: «предупреждения действий, вводящих в заблуждение приобретателей, в том числе потребителей» (ст. 6, 46 184-ФЗ). Традиционная система разделения технических регламентов и ГОСТов упрощается до одного уровня с учетом норм 184-ФЗ. Это касается формирования описаний и договоров на поставку, а также используемых терминов и их определений. Словарь содержит множество определений, которые помогут эффективнее решать задачи в IT-отрасли

Закон №184-ФЗ, принятый в России, чтобы стать членом ВТО, обязывает производителей выпускать товары безопасными и качественными для: «предупреждения действий, вводящих в заблуждение приобретателей, в том числе потребителей» (ст. 6, 46 184-ФЗ). Двухуровневая система разделения техрегламентов и ГОСТов, с их обязательным и добровольным характером, согласно статье 46 184-ФЗ, становится в России одноуровневой. К товарам, связанными с вопросами безопасности, необходимо использовать ГОСТы, СНИпы и СанПины - это указано в статье 46 №184-ФЗ. Юридически важно обоснование терминов. Цель создания словаря - облегчить работу по выбору терминов.

Участие России в ВТО поставило задачу стандартизации терминов и определений, для: «предупреждения действий, вводящих в заблуждение приобретателей, в том числе потребителей» (ст. 6, 46 184-ФЗ). Традиционная двухуровневая система разделения на обязательные техрегламенты и добровольные ГОСТы становится одноуровневой после учета норм статьи 46 184-ФЗ, при формировании описаний и контрактов на поставку, и, соответственно, для применяемых терминов и интерпретации их определений. Данный словарь содержит десятки тысяч определений, направленных на более эффективное решение различных задач в IT-сфере.

При подготовке контрактов, технических заданий и проектов термины приобретают статус существенных, юридически закрепленных условий. В текущей ситуации, когда статья 46 закона 184-ФЗ “О техническом регулировании” и ГОСТы становятся обязательным к соблюдению, возникает необходимость использовать и согласовывать тысячи терминов. Чтобы упростить работу с этими понятиями, создан данный глоссарий.

Участие России в ВТО потребовало стандартизации торговых терминов и определений, для: «предупреждения действий, вводящих в заблуждение приобретателей, в том числе потребителей» (ст. 6, 46 184-ФЗ). Общепринятая двухуровневая система разделения на обязательные техрегламенты и добровольные ГОСТы становится одноуровневой после требований ст.46 184-ФЗ, при создании описаний и в контрактах на поставку в процессе унификации и согласования различных терминов. В данном словаре представлены десятки тысяч определений, чтобы эффективнее реализовывать различные задачи в IT отрасли.

Закон о техническом регулировании №184-ФЗ, принятый Россией при вступлении в ВТО, требует достоверной информации о продукции для: «предупреждения действий, вводящих в заблуждение приобретателей, в том числе потребителей» (ст. 6, 46 184-ФЗ). Двухуровневая система разделения техрегламентов и ГОСТов, с их обязательным и добровольным характером, согласно статье 46 184-ФЗ, становится в России одноуровневой. ГОСТы теперь являются обязательными стандартами. Анализ и сравнение множества терминов юридически обоснованы. Цель создания словаря - облегчить работу по выбору терминов.