17 мая 2024 года. КАМЧАТКА, проект
Выполнен проект✍ отопления административного здания площадью 600кв.м.
Как начать писать документацию в VSCode?
Поговаривают, что в некоторых компаниях сотрудники уже не понимают, что происходит в коде проекта. Де-факто для коллективной работы картография проекта — необходимость, нежели привилегия...
Составление пояснений и комментариев к обширным ИИ-системам — трудоемкая задача, но под небольшие опен-сорс/продакшн проекты есть решение.
AutoDocstring — инструмент, который автоматически создает документацию к коду на основе структуры и комментариев. Экономия времени, согласованность стиля, адекватная читаемость и повышенную точность документации — плюсы этого тула. Выделил нужный блок кода, прожал ctrl+shift+2 — готово.
Просматривать строки документации можно во вкладках, выбирать типы форматов строк, выводить типы параметров через подсказки типов pep484, значения и имена переменных. Внутри поддержка args, kwargs, декораторов, ошибок и типов параметров.
Теперь в утилиту можно добавлять "кастомные" документации. Чтобы использовать собственный шаблон, создайте файл .mustache и укажите путь к нему с помощью конфигурации customTemplatePath.
Сгенерированная документация содержит структурированные описания функций, методов и классов. Однако AutoDocstring не всегда правильно интерпретирует комментарии в коде или не учитывает особенности некоторых языков программирования.
А еще записи могут не соответствовать стандартам или требованиям проекта.
Поэтому редактировать и редактировать. Но для создания костяка описаний инструмент — идеально. AutoDocstring сократит время, затрачиваемое на написание документации, на 30-50%. А еще неплохо так снизит число ошибок в тексте.
Скачать можно с официального сайта Microsoft.
Документация на станки HAAS
Нашел тут диск, с трудом вытащил с него все имеющиеся мануалы на английском и русском
может кому надо:
[Lathe Operator]
96-0118 Russian Lathe.pdf
96-8700 English Lathe.pdf
37 641 Кбайт в 2 файлах/файле
[Mill]
96-0117 Russian Mill.pdf
96-8000 English Mill.pdf
46 866 Кбайт в 2 файлах/файле
[Rotary Tailstock]
96-0166 Russian Tailstock.pdf
96-0315 English Rotary.pdf
96-0328 Russian Rotary.pdf
96-5000 English Tailstock.pdf
17 963 Кбайт в 4 файлах/файле
[Service\Electrical Service]
96-0284C English Elec Service.pdf
96-0304 Russian Elec Service.pdf
Electrical Schematics.pdf
41 047 Кбайт в 3 файлах/файле
[Service\Mechanical Service]
96-0283C English Mech Service.pdf
96-0303 Russian Mech Service.pdf
209 464 Кбайт в 2 файлах/файле
Документация не готова, но систему выкатили? Удачи с техподдержкой!
Пост был взят и переведен с Reddit. Приятного чтения!
Вот вам история про моего находчивого менеджера Service Desk, лучшего менеджера, который у меня был за всю айтишную карьеру. Эта история случилась пару лет назад, но мне очень нравится ее рассказывать, так что поделюсь тут.
Если вы работали в Service Desk, то понимаете: для поддержки самое главное в новой системе — документация к ней и контакты для эскалирования. Работает система или нет — вопрос другой, но, чтобы ее поддерживать, НЕОБХОДИМА документация, иначе команда поддержки просто стреляет вслепую и мало что может. Так вот, давайте перенесемся в далекий 2017 год, когда я работал в банке и они выкатывали новую процедуру для заведения кредитной карты (ничего увлекательнее этого предложения вы сегодня уже не прочтете). Мы должны были отвечать на все вопросы по процессу, и ожидалось, что мы хорошо понимаем, как осуществлять процедуру, что может сломаться, как это чинить и т. д. и т. п.
Что ж, мы с радостью этим всем занимаемся для систем, по которым у нас есть документация! Но руководство по этой системе еще только предстояло написать, вечером перед выносом у нас состоялась большая встреча по этому вопросу, и мой менеджер заметил кое-что странное. Пусть он будет М, а проджект-менеджер, ответственный за систему, будет Мудаком.
М: Слушай, Мудак, выглядит, конечно, классно, и я рад, что функциональное и нагрузочное тестирование прошло успешно, но, кажется, у моей команды не хватает документации для поддержки. Где можно найти эту документацию?
Мудак: А, документация еще в работе, но скоро все будет.
Напомню, до выноса осталось двенадцать часов.
М: Ты хочешь сказать, что документация не будет готова к запуску, но мы все равно запускаемся?
Мудак: Если это проблема, мы можем обсудить ее в офлайне, а сейчас давайте вернемся к важным вопросам.
Их разговор на этом и заглох, и никакого обсуждения в офлайне не предвиделось, но фактически моему менеджеру сказали, что его команда ничего не значит, и он разозлился. И этот потрясающий человек поступил единственно правильным для себя образом.
И вот настал день выноса, и вся наша команда сидит в ужасе, готовясь к наплыву звонков по поводу системы, о которой мы ничего не знаем. Но... Никаких звонков. Вообще ни единого вопроса по новой системе.
Ничего не понимая, я зашел в кабинет к менеджеру и сказал:
— Ого, наверно, эта новая штука очень понятная, а то нам по ней вообще никто не звонил.
— Точно?
— Ага, прямо ни одного звонка. Что происходит? Ты что-то придумал?
— А ты попробуй прямо при мне позвонить в поддержку.
Этот парень, этот бог итальянских забастовок изменил алгоритм переадресации звонков поддержки так, чтобы первым делом звучало: «Если вы звоните по поводу [новой системы], нажмите 1, и мы переключим вас на поддержку новой системы» — и такие звонки перенаправлялись прямо на рабочий номер проджект-менеджера новой системы. У него уже висела очередь из пятидесяти звонков, и конца им не было видно.
Весь день я замечал, что к моему менеджеру в кабинет ходят какие-то люди, и каждый раз он указывал им на плакат «Правила поддержки Service Desk» (долгая история, но это был официальный распорядок технического отдела, подписанный техническим директором), и первым пунктом там стояло: «Если система не задокументирована, Service Desk ее не поддерживает».
По логике, если Service Desk что-то не поддерживает, следующая линия поддержки — это проджект-менеджер, ответственный за новую систему, по крайней мере, таким дурацким образом работала банковская техподдержка. Если наша третья линия не справлялась, мы обращались к менеджеру, ответственному за проект, и дальше разбиралась их команда. Применив эти два правила, мой менеджер смог убедить своего начальника (технического директора) включить переадресацию звонков по новой системе сразу тому проектному менеджеру.
Документация была готова через два дня, хотя изначально говорили про две недели.
Долой бумажную волокиту! Ученые ПНИПУ разработали программу для написания технической документации
Большинство работников регулярно сталкивается с рутинной, но очень нужной работой с документами. На написание технических заданий, отчетов и прочих проектов со множеством формальных правил тратится большое количество человеческих и временных ресурсов. Ученые Пермского Политеха разработали интеллектуальную систему помощи «Техдок менеджер», которая быстро и точно создает документацию по заданным правилам за секунды. Современные нейросети не умеют следовать четким стандартам, таким как ГОСТ, результаты их работы требуют тщательной проверки в отличие от программы политехников. Она поможет исключить фактор человеческой ошибки, ускорить работу и автоматизировать шаблонные процессы.
На разработку выдано свидетельство №2024612000.
Для написания технической документации компании чаще всего нанимают отдельных специалистов – технических писателей. Они разрабатывают инструкции по эксплуатации, руководства пользователя, отчеты и другие материалы, которые помогают понять и использовать различные продукты, технологии или услуги. Еще такие люди пишут документы технической спецификации, больше ориентированные на разработчиков или отчетность. Помимо самого написания требуется соблюдать определенные правила и ГОСТы.
Но не только технические писатели сталкиваются с подобной задачей. В обязанности многих сотрудников входит ведение документации, особенно в государственных организациях. Например, преподаватели в своей практике часто встречаются с необходимостью формирования целого перечня документов: рабочая программа дисциплины, методические указания к лабораторным и практическим работам, фонд оценочных средств.
Ученые Пермского Политеха разработали программу для компьютеров «Техдок менеджер» – это интеллектуальная система помощи техническому писателю. Программа помогает избежать человеческих ошибок (что-то пропустить или перепутать), «интеллектуально» отслеживает даты, термины и прочее. Автоматизирует рутинные процессы и ускоряет документооборот. «Техдок менеджер» может сам следить за выполнением плана работ над проектом без внесения дополнительных данных. «Помощник» легко модифицируется и настраивается под различные задачи и создает множество альтернативных решений.
Логика разработанной программы построена на классификации и кластеризации текстов различной длины, поиске и распознавании сущностей (конкретные объекты или понятия, которые имеют уникальное имя и могут быть идентифицированы в тексте, например, имена людей, названия организаций, даты и т.д.). «Техдок менеджер» извлекает и систематизирует факты из текста, собирает данные для обработки и понимания естественного языка. Он выявляет содержательные, логические и фактические ошибки, а еще распознает литературные приемы и стили. В итоге синтезирует человеко-читаемый текст на основе выявленной ранее информации и запросов пользователей.
– Ключевая задача нашей программы в том, чтобы одни документы или их части, содержательно зависимые от других, заполнить автоматически. Например, из техзадания органично вытекает технический проект. Его большую часть можно автоматически составить как заготовку документа, но человек должен внести правки. От них уже зависит, например, содержание таких частей как «Введение», «Заключение» и «Список использованных источников». Их можно отредактировать автоматически, – поделился кандидат технических наук, доцент кафедры информационных технологий и автоматизированных систем Даниил Курушин.
Средств автоматизации разработки документации достаточно много, но они чаще всего ориентированы на решение других проблем. Например, современные нейросети способны выполнять рерайтинг и синтез текста, однако результат их работы требует проверки, поскольку они не созданы для работы по стандартам ГОСТ. Разработка ученых ПНИПУ отличается тем, что использует синтез нейронных сетей и специального метода моделирования данных.
– «Помощник техническому писателю» формируется как интерфейс к разрабатываемым нами микропрограммам, скриптам, автоматизирующим работу специалиста. Сначала возникло понимание, что, например, вопросы к курсу лекций можно не сочинять, а написать программу, которая сгенерирует их вместе с вариантами правильных и неправильных ответов. Разумеется, планируется использовать и современные языковые модели, такие как GPT и другие генеративные сети. Также предполагается работа по автоматизированному составлению словарей и справочников, – рассказывает Даниил Курушин.
Программа будет реализована в виде веб-приложения (сайта). Для создания готового текста пользователю необходимо выбрать стандарт, этап и тип документа, который необходимо сформировать, а также написать в окно чата запрос с уточняющими деталями.
«Техдок менеджер» поможет избавиться от рутинной работы. Сейчас ученые Пермского Политеха сами пользуются программой, а в течение года обещают выпустить полноценный продукт для пользователя. Помощника можно будет применять в сфере образования, при разработке продуктов и для сопровождения программного обеспечения.