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

При разработке и производстве программно-аппаратных комплексов в первую очередь думают о функциональности для конечного потребителя. Сложная система типа сервера или системы хранения данных (СХД) должна работать без сбоев, не отставать в производительности от конкурентов, эффективно решать задачи пользователей. Вопросы комфорта обслуживания и диагностики таких систем сервисными инженерами и заказчиком зачастую имеют более низкий приоритет.

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

В данной статье обсудим процедуру размещения заявки в ГИСП, порядок внесения документов с их ранжированием по разделам и поясню как заполняются шаблоны.

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

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

В этой статье мы поделимся своим опытом создания документации «с нуля» на примере Arenadata.

В этой статье я расскажу, как грамотно подготовить для реестра Минпромторга пакет документов, подтверждающих что ваша продукция произведена на территории Российской Федерации (исполнение требований ПП № 719 или Соглашения).

Приветствую, уважаемые читатели Хабра! ??‍?

В мире разработки программного обеспечения существует множество вызовов, и одним из них является столкновение с проектами, лишенными должной документации. Это часто вызывает чувство потерянности и озадаченности, подобно тому как путник оказывается в темном лесу без карты и компаса. В таких моментах первая мысль, которая приходит в голову, - "Может, лучше свернуть назад?"

Однако, несмотря на первоначальное замешательство, такие ситуации предоставляют уникальную возможность стать настоящим героем проекта. Представьте себе, каким уважаемым и крутым специалистом вы станете, создавая систему документации с нуля!

С таким мощным стимулом я и решила приступить к делу:

В этой статье я расскажу, как зарегистрировать предприятие в ГИСП, и как создать на примерах свой каталог продукции. Правильно обозначим каждое наименование и оформим технические характеристики продукции.

ГИСП (государственная информационная система промышленности) – это государственный реестр промышленной продукции, произведенной на территории Российской Федерации.

Эта статья рассказывает, как внести продукцию в реестр Минпромторга, о преимуществах, которые получит производитель, а также, как правильно применить коды ТН ВЭД и ОКПД2 для формирования необходимого пакета документов.

Если простыми словами, то реестр Минпромторга – это база данных, в которой содержится информация о продукции, произведенной российскими производителями.

В статье я хочу рассказать об одной очень интересной теории разработки документации на системы и программы. Её авторы утверждают, что создали ни много ни мало «Великую Единую Теорию Документации» (The Grand Unified Theory of Documentation). Мы привыкли с опаской относиться к заявлениям о том, что кто-то обнаружил сокровенную истину и раскрыл её профессиональному сообществу. В теории изложены идеи и правила, которые мы встречаем в разных методиках разработки документации и сами применяем на практике.

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

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

Я начал коллекционировать самые фееричные комментарии. Делал я это для того, чтобы иметь перед глазами антипример — как ни в коем случае нельзя писать комментарии к текстам. Эти советы — тщательно отобранные, систематизированные и дистиллированные советы для проверяющих. Практическое руководство по доведению до белого каления ваших технических писателей и авторов.

Дисклеймер. Все совпадения фрагментов этого текста с реальными комментариями в вашей документации совершенно случайны. При написании этого текста не пострадал ни один проверяющий.

Ставится задача повторить доселе непревзойдённый ARIS SmartDesign, который по табличному представлению процесса автоматически рисует схему процесса (структуры чего-либо). Схемы процессов желательно строить в нескольких процессных нотациях (EPC, VAD и т.п.). ARIS SmartDesign также умеет по табличному представлению орг-структуры (другой древообразной взаимосвязи) строить иерархическую схему (тут рассмотрим только процессные схемы).

Системы / Инструменты ВРМ (Business Process Management System/Tool) часто представляют из себя что-то очень сложное и дорогое. Чтобы работать с ними для формализации (моделировании, описании) даже простых процессов нужно много учиться, включая зазубривание различных нотаций. Ниже показан вариант как на простом инструменте можно составить схему своего процесса «с нулевой» подготовкой в области BPM. Достаточно заполнить несложную табличку и получить схему процесса в нескольких нотациях, как это показано на заставке. Инструменты типа SmartDesign реализуют подход «таблица с процессом в схему процесса».

Работа с рассмотренными ниже инструментами SmartDesign – чрезвычайно проста и не требует никаких навыков. Статья может показаться сложной, вследствие того, что в ней много посвящено сравнению ARIS SmartDesign vs DOT SmartDesign и рассмотрены технологические аспекты обоих инструментов, которые рядовому пользователю не понадобятся. Однако в сущности нам нужно просто заполнить таблицу и мы сразу получаем его схему.

Только в системе ARIS (самая известная BPM-система) ранее была представлена реализация SmartDesign, концепцию которого можно назвать инструментом «моделирование без моделирования», по аналогии «программирование без программирования». Несмотря на долгое существование и наличие его не только в платной версии ARIS, но и в ARIS Express – этот инструмент остается недооцененным и поэтому в целях его популяризации предлагается альтернативная реализация DOT SmartDesign, причем в нескольких вариациях (excel, javascript).

Может ли IT-продукт жить без документации?

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

Хабр, привет!

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

Идеальная документация должна выполнять две основные функции...

Одна из злободневных тем, которая постоянно вызывает жаркие споры в комментариях — перевод технических текстов, в том числе терминов. Кто-то уверен, что переводить нужно, кто-то резко против, есть и те, кто считает, что оригинальные термины в русском тексте должны быть написаны по-английски.

Независимо от выбранного подхода, сложно поспорить с тем, что переводов плохого качества действительно очень много. Одна из причин заключается в том, что переводящие текст люди — не обязательно переводчики.

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

Привет, Хабр! В 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-систем и каких-либо других инструментов перевода.