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

Привет, хабр! Я технический писатель в компании Bimeister. 

Наша компания занимается разработкой программного обеспечения для автоматизации крупных производств. Вместе с тем мы разрабатываем большой объем технической и проектной документации. Так получилось, что Заказчики наших продуктов стремятся к соблюдению требований государственных стандартов (далее — ГОСТ), поэтому всю отчетную документацию мы пишем в соответствии со стандартами.

Кажется, что все достаточно просто — пишешь по ГОСТ, и все остаются довольны. Но, как показывает практика, не всё так однозначно как должно быть в документах уровня ГОСТ, и у каждого Заказчика есть свое видение относительно требований стандартов, под которое нам приходится подстраиваться.

Требования Заказчика будут проходить красной нитью по всей статье, поэтому сразу приведу цитату, которая успокаивает мне нервы в такие моменты:

Всем привет!

Решил немного отойти от своей любимой темы нейронных сетей и написать небольшой скрипт на Python для работы с конструкторской документацией в САПР «SolidWorks». Так как изначально у меня инженерное образование, то мне периодически приходится заниматься конструкторской деятельностью и, по своему опыту, я знаю, как много иногда приходится тратить времени для оформления чертежей и сохранения их в формате pdf или dwg (особенно, если мы говорим о большом количестве деталей сборок). И тут я подумал, почему не упростить жизнь себе и своим коллегам-конструкторам и не подружить Python и SolidWorks.

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

Работа будет состоять из двух основных частей (соответственно и статей будет две):

Часть 1 – Создание общей базы для работы с SolidWorks, написание простого графического интерфейса на tkinter, реализация возможности сохранения чертежей в форматах pdf и dwg.

Часть 2 – Реализация возможности автоматизированного заполнения полей таблицы чертежей из единого excel файла, и самая интересная фича этого проекта: автоматическое создание чертежей деталей из 3D-моделей (для начала реализация простых деталей из листового металла).

По итогу «завернём» программу в один .exe файл для возможности использовать на любых машинах.

В этой статье я расскажу о генераторе документации Sphinx, с помощью которого можно автоматически создавать документацию для модулей Python. Кроме того, я буду использовать шаблон проекта Cookiecutter Data Science в Visual Studio Code (VS Code), поскольку он легко интегрируется в Sphinx и имеет стандартизированную структуру директорий. Официальное пособие по использованию Sphinx — отличный ресурс для пользователей, которые хотят углубиться в детали. А моя статья — это краткое руководство по началу работы с этим инструментом.

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

Более трех лет назад в 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.