Всё о деятельности технических писателей
Потерянные версии документов, поиски актуальных планов и отчетов, несоответствие статус проекта и реального состояния... Такое знакомо многим и менеджерам проектов, и спонсорам, и командам (которые считают, что проще написать заново). Дело не в плохих людях, а в отсутствии системы, которая учитывает статусы и этапы проектов.
С проблемой терминологии сталкивается каждый технический писатель. Многие ИТ-термины заимствованы из английского языка и имеют несколько вариантов перевода, или не переводятся вовсе. Для создания терминологии необходимо проанализировать существующие термины и их использование, выбрать единый стандарт написания и сделать термины понятными для всех членов команды.
Мы — команда документирования платформы Platform V в СберТехе: Лидия Ковач, middle технический писатель, Мария Бурханова, senior технический писатель, и Светлана Каюшина, руководитель команды. Хотим рассказать, как мы разработали глоссарий, который повысил качество документации нашей цифровой платформы для построения ИТ‑ландшафта.
Поделимся тем, как устроен наш глоссарий, с какими трудностями мы столкнулись и какими инструментами пользовались. Надеемся, это поможет вам добиться точности и единообразия терминологии в вашей компании.
Сегодня расскажем, как инженеры центра «ПрофИнформЗащита» внедрили nanoCAD BIM ОПС и смогли существенно сократить сроки подготовки проектной документации на примере реальных кейсов.
Всем привет, меня зовут Максим, я QA-специалист в компании SimbirSoft. Более двух лет я занимаюсь обеспечением качества, за это время мне часто попадались проекты с отсутствующей или устаревшей технической документацией. Как быть в подобной ситуации и при этом сохранить нервные клетки, я расскажу в этой статье.
Бывают ситуации, когда тестировать приходится вопреки. Вопреки срокам, здравому смыслу или отсутствию требований. Именно последний кейс мы и разберем с вами сегодня 🦾
Пока разработчики по всему миру мучаются с ChatGPT, пытаясь выжать из него хоть что-то приличное для технической документации, команда Artezio пошла другим путем. Вместо того, чтобы полагаться на сырой ИИ, мы создали «Кентавр» — гибридную систему, которая объединяет возможности больших языковых моделей с экспертизой опытных аналитиков.
В результате то, на что enterprise-команды тратят месяц (на подготовку полного пакета требований на 60-100 страниц), задействуя несколько специалистов, «Кентавр» делает за пару дней силами одного аналитика. При этом документы качественнее: структурированные, непротиворечивые и главное — повторяемые от проекта к проекту.
О том, как создавалась эта система, с какими проблемами столкнулись разработчики и почему простого ChatGPT недостаточно для серьезной документации, рассказали Андрей Шагалов, директор по маркетингу Artezio, и Денис Харченко, директор по развитию бизнеса компании. Они поделились техническими деталями архитектуры, объяснили концепцию Human-in-the-Loop и раскрыли планы по превращению нового инструмента в популярный коммерческий продукт.
Технический писатель — своего рода проводник между разработчиками и пользователями. Мы берём техзадания, обрывочные комментарии, макеты, проходим процессы в продукте и создаем понятные инструкции. Часто на стадии подготовки возникают вопросы: «Где искать информацию — и какую?»
В некоторых командах проблема решается с помощью продактов, тимлида или автоматизации распределения задач. Однако так бывает далеко не всегда, и ответы могут найтись не сразу, особенно при высокой загруженности и в хаосе задач. Неожиданно, простая подсказка пришла из мира аниме: в сериале Mononoke (не путать с Принцессой Мононоке) персонаж по имени Аптекарь изгоняет злых духов, используя метод: «форма, суть, причина». Если не смотрели — не беда, в первую очередь мы говорим о структурированном подходе к поиску информации.
Меня зовут Александр Панов, я занимаюсь разработкой документации в Test IT и расскажу, как подход из аниме помогает структурировать работу и создавать понятные доки. Мы обсудим методологические аспекты и рассмотрим практический пример. В конце статьи вы найдете небольшой чеклист, где все данные сведены в таблицу.
В предыдущей статье мы рассмотрели, как система Документы способствует выстраиванию процесса управления документацией в административно-хозяйственном отделе (АХО). На этот раз мы рассмотрим отдел кадров.
Это короткий пост, вдохновлённый карточками по теме, которые я встретил на канале S0ER'а. В геймдеве такая практика встречается нечасто. Поэтому внесу дополнительное упоминание в ленту. Оставлю вводные, ссылки на более подробное изучение, поделюсь своим опытом и расскажу, какое отношение к этому имеет AI.
Привет, Хабр! Меня зовут Мария Бурханова, я технический писатель, старший руководитель ИТ-направления документирования Platform V в СберТехе. На TechWriter Days я рассказывала, как техническому писателю научиться читать и понимать сложные нотации, чтобы сделать документацию простой и понятной.
Сегодня хочу рассказать, зачем техпису нужны нотации и почему их так много, какие знания о нотациях точно пригодятся и как применить эти знания на практике.
Статья будет полезна техническим писателям, аналитикам, разработчикам и всем интересующимся этой темой. Вы научитесь читать диаграммы и схемы в разных нотациях и эффективно использовать их для создания понятной и структурированной документации.
Diplodoc - платформа для создания технической документации в концепции Docs as Сode с открытым исходным кодом.
С помощью Diplodoc можно создавать документы любой сложности, быстро валидировать их и выкладывать в общий доступ, а также настраивать интеграцию с системами автоматической документации. Именно на этой технологии построена документация сервисов Яндекс.
В данной статье я расскажу, как создать базовый скелет документации на примере собственного многостраничного лендинга.
Всем привет! Решил я тут собрать в кучу все свои знания по онбордингу новых сотрудников поддержки. За свою карьеру я построил несколько отделов саппорта с нуля и, признаться, порядком устал от бездушных корпоративных регламентов, от которых клонит в сон уже на третьей странице. Писать очередной талмуд «делай хорошо — не делай плохо», который никто не дочитает, — гиблое дело, особенно для молодого поколения, выросшего в эпоху TikTok.
В организациях зачастую можно наблюдать картину, когда разные отделы используют разные системы создания и ведения документации. Это ведет к нескольким проблемам:
• Отсутствие контроля структуры и содержания документа.
• Проблема совместимости файлов и форматов.
• Отсутствие единого хранилища и версионированию.
• Замедление согласования из‑за отсутствия интеграции с системами электронного — документооборота.
• Дублирование документов.
• Сложность с отчетностью и аудиторскими проверками — документы, в т.ч. архивные, не хранятся централизованно.
• Дополнительные затраты для обучения персонала и поддержке нескольких систем.
Как можно решить всю совокупность этих проблем? Лучшим вариантом является гибкая система документооборота с возможностью согласования документов прямо в системе, единым хранилищем документов (в том числе архивных) и возможностью отслеживания версий документов, которая может быть использована во всех отделах компании, чтобы не увеличивать количество используемых инструментов и затраты на поддержку систем в компании. И на рынке есть система, удовлетворяющая всем этим запросам — это Сфера.Документы.
Рассмотрим конкретный бизнес‑сценарий, когда административно‑хозяйственному отделу (АХО) нужно закупить мелкое оборудование для ремонта офиса.
Рассказываем о возможностях nanoCAD BIM Строительство для проектирования мостов и линейных сооружений, включая создание параметрических объектов, работу с библиотеками и интеграцию с другими BIM-решениями. На примере обучения сотрудников «Института Стройпроект» показано, как инструменты программы позволяют эффективно моделировать сложные конструкции, автоматизировать процессы и адаптировать решения под конкретные проектные задачи.
Прошло целых два года, как команда NSR Specification твердо пообещала добиться автоматизации экспертизы цифровых информационных моделей (ЦИМ) за счет создания машинопонимаемых представлений требований стандартов проектирования. На тот момент мы очень хотели регулярно рассказывать о промежуточных результатах, но слишком увлеклись разработкой. Ежедневно возникали новые и новые проблемы, в муках рождались способы их решения, в спешке писались задачи на разработку, когда заканчивались слова мы рисовали картинки, потом, дрожащими руками тестировали новый функционал, с азартом отлавливали баги, умело замаскированные под фичи... Каждый раз нам казалось, что осталось только дождаться свежего релиза, и все, мы победили. Оглядываясь назад, мне все чаще кажется, что мы были немного сумасшедшими, раз взялись за эту задачу. Но это, наверное, к лучшему. Если бы тогда, в 2023 году мы знали обо всех сложностях, с которыми нам предстоит столкнуться, то сегодня не смогли бы похвастаться работающим решением. Теперь то уж точно нам есть о чем рассказать: решение работает и уже обкатано на нескольких пилотных проектах.
Документация играет важную роль в эффективной работе, особенно в условиях крупных и сложных инфраструктур. Она не только облегчает понимание существующих решений, но и ускоряет процесс интеграции новых технологий. Поэтому, например, важно иметь базу знаний по облачным технологиям.
Мы уже рассказывали об инструментах для сборки и работы с README. Сегодня перейдем к конкретным примерам для вдохновения: элементам, которые могут быть полезны в README: от блоков с пояснением лицензий до различных схем и диаграмм.
Привет, Хабр!
Я Дима, работаю техническим писателем в UDV Group, описываю разрабатываемые продукты для внешних и внутренних пользователей.
Задумывались ли вы когда-нибудь о том, кто объясняет сложное так, чтобы было понятно всем? Кто превращает техническую жаргонизированную речь разработчиков в простые инструкции, которые может прочитать любой — от новичка до супер-специалиста?
Технический писатель — одна из критически важных ролей в IT, но многие о ней не слышали. Кто-то думает, что это просто «оформитель документов», «специалист по документообороту» или «тот, кто пишет инструкции к стиралкам». В своей статье я попытаюсь рассказать о профессии технического писателя на примере конструирования моста.
Дисклеймер для тех, кто не смотрел «Друзей»
Моника Геллер — персонаж культового ситкома 90-х, безумно одержимая порядком. Её чек-листы для чек-листов, лейблы на лейблах и фетиш сортировки по цвету и размеру превратили её в мем про педантизм. Но именно Моника в сериале всегда вытаскивала друзей из провалов: когда нужно было за 3 часа организовать свадьбу, найти документы за 5 лет или просто понять, кто последний брал фондюшницу.
В реальной жизни мы живём не в квартире с purple дверью, но законы Моники работают лучше любого скрам-майнд-сета.
С каждым днем команда RedKrab разрабатывает все больше проектов на базе ИИ. Ввиду того, что основная сфера студии - это промышленность и производство, то всё чаще приходят обращения от заводов и предприятий за помощью в внедрении сложных ИИ-систем.
Один из крупных заводов по производству деталей для конвейерного оборудования обратился с проблемой - совсем небольшое отклонение в доли миллиметра могло привести к браку, претензиям со стороны клиентов и остановке всей производственной линии. Ручной контроль, даже силами опытных специалистов, все чаще пропускал дефекты. Усталость, рутина и скорость работы мешали поддерживать качество. Технолог завода сообщил о том, что проверка происходит выборочно, но этого недостаточно. Если будут пропуски, то это приведет к затяжным разбирательствам, убыткам и потере доверия. С нашей стороны было предложено решение - сделать контроль непрерывным, быстрым и точным. Так стартовал проект по разработке ИИ-системы для завода по производству деталей механообработки.
Идея полностью автоматизированного контроля без снижения скорости производства раньше звучала как фантастика. Сейчас на помощь приходит искусственный интеллект. ИИ трансформирует процесс проектирования, предлагая революционные возможности там, где традиционные методы уже не справляются.
Наша команда разработала для клиента систему, которая выполняет конкретные функции: обнаруживает дефекты, анализирует причины и предотвращает их появление. За несколько секунд после обработки детали она проходит через четыре этапа проверки: визуальный анализ, измерение параметров, сравнение с эталонами и принятие решения. Каждый этап приближает производство к идеальному качеству. Система, разработанная для нашего клиента, использует методы компьютерного зрения для измерения геометрических параметров деталей и определения дефектов.
Компания АО «НижневартовскНИПИнефть» (г. Нижневартовск) решает комплексные задачи обустройства нефтяных и газовых месторождений, расположенных в регионах с различными природными условиями и отличающихся насыщенной промышленной инфраструктурой. Институт постоянно отслеживает новейшие технологии и методы, используемые для совершенствования процессов разработки месторождений нефти и газа, развивая и укрепляя отношения с отечественными и зарубежными научными организациями и разработчиками технологического оборудования.
С помощью nanoCAD Конструкции PS ООО «АРТ» автоматизировало проектирование железобетонных конструкций, что позволило сократить количество ошибок, ускорить процесс армирования и автоматизировать подсчет спецификаций, значительно повысив эффективность работы над проектами.