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

Всем привет. В последнее время перевод текстов с одного языка на другой уже не вызывает такой головной боли, как раньше: есть несколько качественных онлайн-переводчиков, есть большие нейросети, которые тоже можно попросить перевести текст, — в общем, варианты есть, их довольно много, и они выдают вполне приемлемый результат. Но у всех них есть одно ограничение: они работают онлайн (удалённо). Для кого-то это ограничение несущественно, а для кого-то может быть критично. Мне же просто захотелось иметь что-то, что сможет переводить тексты на хорошем (современном) уровне офлайн (сугубо на моём компьютере). Ну, люблю я, когда всё, что мне нужно, может работать и локально тоже. В общем, ниже я делюсь с вами тем, что мне удалось в итоге собрать, запустить и даже получить удовлетворяющий меня результат.

Опытного конструктора сложно чем‑то удивить, но давайте попробуем вспомнить то захватывающее чувство, когда открываешь крышку механизма, не имея вообще никакого понятия о том, что внутри. Душа замирает, в глазах — предвкушение, в голове — мысли типа «надеюсь, это не очередная китайская импровизация на тему „как сделать сложно, когда можно просто“». Сегодня мы поговорим о магазине инструментов для металлорежущего станка.

Запуск любого производства, будь то сервера для дата-центра или бытовой электроники, строится на трёх ключевых столпах: техническая документация (ТД), тестовая оснастка (ТО) и тестовое программное обеспечение (ТПО). Эти три элемента — основа реализации массового производства: от первого прототипа до серийной партии. Но довести их до совершенства практически невозможно. Всегда можно сделать что-то лучше: добавить новые функции в ПО, сделать новый чертёж в ТД или улучшить функциональность тестовых стендов. Однако жесткие сроки, бюджеты и нехватка ресурсов заставляют выбирать, где быть идеалистом, а где — прагматиком.

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

Привет, я — Таня Кириллова, технический писатель команды развития безопасности контейнеров в Cloud.ru.

На конференции Techwriters Days 2 Семён Факторович, основатель и руководитель компании documentat.io, в своем докладе Техписатель-2025 предложил ввести специализации для профессии «Технический писатель». В качестве одной из таких он выделил направление Cloud-техписатель. 

Чем Cloud-техписатель отличается от обычного технического писателя? Тем, что извлекает информацию из голов разработчиков и самих сервисов, адаптирует собранную информацию для пользователей, разрабатывает практические сценарии совместно с девопсами, работает с документацией, как с кодом, документирует API, пишет Release Notes… и все это для облачных сервисов.

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

Подробное руководство по работе с параметрами и автоматизации оформления чертежей в nanoCAD BIM Строительство. Особое внимание уделено инструментам для ускорения оформления документации: мастерам размеров, настройке выносок и маркеров.

Добрый день, уважаемые читатели! Не так давно я проводил внутрикорпоративное мероприятие о том, как правильно применять чат-ботов, чтобы немного ускорить офисную рутину. Мероприятие очень понравилось аудитории, поэтому я решил переработать презентационный материал в статью - вдруг он принесет пользу еще кому-нибудь?

Если вы уже используете приемы промт-инжиниринга - то, скорее всего, вы не найдете для себя ничего нового. Статья больше рассчитана на тех новичков, которые лишь «что-то слышали» о больших языковых моделях, но не используют их в работе, поскольку это «что-то на ITшном», «не понятно, как это может мне помочь», «я слишком занят, чтобы разбираться самому». Можете переслать эту статью вашим офисным коллегам 💼.

Итак, поехали!

Всем привет, с вами Анастасия Жилкина, системный аналитик ГК Юзтех. На данный момент работаю в команде, которая занимается реализацией и развитием онлайн-оплат на сайте. В этой статье хочу рассказать о процессе ревью документации, который мы внедрили в команде, и о том, какие ощутимые плюсы это дало как в качестве итоговых решений, так и в командной работе в целом.

Этот опыт может быть полезен системным и бизнес-аналитикам, а также менеджерам проектов, разработчикам и тестировщикам, которые работают с требованиями и участвуют в создании цифровых продуктов.

Всем привет. Меня зовут Татьяна Цикунова. Я системный аналитик в компании МойСклад. В этой статье расскажу о том, как организовать оперативный обмен информацией между участниками проекта и поддерживать документацию в актуальном состоянии Отдельное внимание уделю работе с таск‑трекерами — подробно опишу шаблон тикета, который успешно используется в нашей компании. Однако — если вы работаете без трекера задач, например, в ворд‑файлах, суть от этого не меняется ‑такой подход работает и с другими инструментами.

Я документирую системы больше 3 лет, и за это время успела поработать в разных сферах.. Начинала в финтехе, где успела поработать в разных командах. Потом перешла в МойСклад — здесь углубилась в e‑commerce направление. Сейчас вместе с командой делаем интеграции с интернет‑магазинами и маркетплейсами. За годы работы я убедилась, что не существует единого стандарта ведения документации — каждая компания и даже отдельные команды внутри одной организации вырабатывают свои подходы. маркетплейсами. В разных компаниях свой подход к ведению документации, даже в разных командах одной компании бывают разные подходы.

Однажды в МоемСкладе мы задумались: почему бы не начать системно собирать важные данные, которые появляются на разных этапах разработки? Ведь эти сведения могли бы стать отличной основой для обновления документации к реализованному ПО. Так и появились требования и рекомендации по описанию тикета.

В статье рассматривается опыт команды технических писателей Deckhouse по внедрению автоматизированной проверки орфографии в документации. Описываются причины, по которым проверка текста является важной частью работы с документацией, а также анализируются различные подходы к решению этой задачи: от ручной проверки до автоматизации. Подробно разбираются этапы выбора и интеграции инструмента Hunspell в пайплайн CI/CD, особенности работы с различными форматами файлов (Markdown, HTML, YAML), настройка контейнерной среды и создание кастомного словаря терминов. Приводятся практические примеры реализации и результаты автоматической проверки в процессе работы с документацией.

Научимся превращать бизнес-требования в рабочую схему БД и документировать ключевые решения! Без недопонимания, технического долга и смс.

Представьте, что вы разработали программное обеспечение. Все идеально: код отточен, тесты пройдены, система готова к работе. Но тут встает вопрос: как отправить документацию заказчику?

Всем привет! Меня зовут Катя, я развиваю Gramax, open source-платформу для управления технической документацией. В этой статье хочу поделиться впечатлением от стандартных способов передачи документации на заказную разработку. А также рассказать о том, как этот процесс можно автоматизировать с помощью Gramax.

Какие бывают схемы

Это история о том, как я устал держать в голове инфраструктуру по всем своим проектам.

Прод падает — а ты тратишь время на то чтобы вспомнить где лежит Grafana, где настраивается DNS, чей Docker Registry мы используем, есть ли у нас CDN и какой.

В итоге я запилил легковесное решение чтобы разобраться с вопросом системно, а не просто наклепать закладок в браузере.

На этом Google IO google показал новый инструмент разработки - https://jules.google.com

В чем плюсы: пока бесплатный, работает на gemini, и это AI Agent.

Что это значит (пример):
Часто бывает проблема, что кол-во модулей в проекте или библиотек которые хотелось бы сделать, превышает кол-во которое можно поддерживать. Особенно если ведешь open source библиотеку.

Background агенты позволяют взять часть работы - нашел полезными для документации, легкого рефакторинг и имплементирования небольших фич.

Чтобы начать, обычно можно использовать небольшой промпт чтобы предсоздать план по которому Jules будет частично следовать (на самом деле она пересоздаст план, но имея рефренсы ей будет проще):

Всем привет! Меня зовут Катя, я развиваю Gramax, open source-платформу для управления технической документацией.

В нашем чате и у пользователей регулярно встает вопрос переезда в Gramax c других платформ. Переезд с Confluence и Notion мы сделали прямо в интерфейсе приложения, а с Yandex Wiki — отдельной утилитой. Нет, мы не поленились, просто заметили, что сообщество Yandex Wiki такое давно просит: пример №1 (367 голосов), пример №2 (874 голоса).

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

Ну хорошо, не поразило. Но понравилось настолько, что я записала это в свой блокнот, а теперь, спустя 13 лет, делюсь с вами. Если вы работаете с документацией, интерфейсами или пишете ТЗ или bug reports, эти заметки будут вам полезны. Кстати, вот первая часть статьи — взгляните, если пропустили.

Diplodoc — опенсорс‑платформа для работы с документацией в парадигме Docs as Code, которая создаётся в Яндексе силами команд Yandex Infrastructure и Yandex Cloud и является частью наших опенсорс‑инструментов. С её помощью мы собираем всю документацию компании. Это суммарно более 300 тысяч статей в более чем 2500 документационных проектов и порядка 6000 запусков Diplodoc CLI каждый день.

На таких объёмах нам важно быть эффективными — умеренно расходовать ресурсы сборочных ферм и при этом собирать проекты как можно быстрее, чтобы документаторы могли увидеть финальный результат без смены контекста на чай.

Со временем, скорость CLI заметно деградировала. С одной стороны, платформа прирастала полезными функциями, это увеличивало время обработки контента, с другой — размер документации вырос и для некоторых продуктов перевалил за тысячу файлов.

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

Привет, Хабр! Я Александр Зырянов, проектный менеджер TMS с открытым исходным кодом TestY. Сразу о главном: выложили в open source версию TestY 2.1. 

Во-первых, подвезли любимую фичу всех разработчиков — темную тему. Дочитайте до конца, чтобы посмотреть, как выглядит интерфейс различных страниц. Во-вторых, совместно с командой технических писателей YADRO разработали удобную документацию, чтобы погрузиться в работу системы с головой.

Какие еще изменения ждут пользователей в TestY 2.1 — читайте под катом.

А вы никогда не задумывались, почему, с одной стороны, у нас появляются всё более крутые и мощные инструменты для разработки? На бэкенде мы можем делать микросервисы, писать офигительные SPA-приложения — но при этом будто бы сама программа становится всё хуже и хуже.

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

Откуда берётся эта эрозия программного обеспечения? Почему так выходит, что новые технологии не только не помогают, но иногда даже мешают нам писать качественные программы? Почему, когда мы стараемся делать хорошо — получается плохо?
И главное — что с этим делать?

«А в ТЗ этого не было!» — знакомая ситуация?

Проблема, которая часто возникает: ТЗ составляются формально, без должной детализации — слишком абстрактно, без примеров или с пробелами в логике.