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

Пошаговое руководство по использованию Git, Obsidian, Markdown и любимого IDE для разработки требований и трассируемого в них программного кода.

НПИ ОНГМ перешел на Платформу nanoCAD, что позволило ускорить проектирование нефтегазовых объектов за счет автоматизации чертежей и улучшения междисциплинарного взаимодействия. Интеграция с системой управления данными оптимизировала документооборот и повысила эффективность инвестиционно-строительного процесса.

Добрый день! Меня зовут Воронин Николай, я занимаюсь автоматизацией систем отчётности и анализа в ПГК Диджитал.

Моя статья является структурированием личного опыта, полученного в конкретных условиях, он не претендует на статус best‑practice, допускает ситуации, в которых могут существовать более эффективные решения или проблема не стоит в целом.

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

В моём случае речь пойдёт о комплексе нескольких BI систем, существующих параллельно, но сложности вполне могут возникать и в рамках одной, достаточно массивной системы отчётности.

Давайте знакомиться. Я Иван Холодков, старший технический писатель направления производственной документации в YADRO. На производстве документация важна не меньше, чем сборка, тестирование или упаковка. Когда завод работает в режиме 24/7, а у сотрудников нет времени на раздумья, инструкции становятся их основным инструментом.

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

Многие компании в России столкнулись с ситуацией, когда привычные облачные сервисы прекратили работу, а данные оказались заперты в проприетарных форматах, которые без специальных инструментов не открыть.

Концепция «Файл вместо приложения», предложенная Стефаном Ангом, сооснователем Obsidian, предлагает решение: переместить фокус с инструментов на данные, обеспечив их доступность, долговечность и независимость от конкретного ПО.

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

О чем статья:

⚪что такое UI-kit состояний интерфейса и какие компоненты в него входят (экраны успеха, ошибок, пустых состояний и т.д.),

⚪зачем команде его поддерживать,

⚪как собрать и поддерживать UI-kit.

Кому будет полезна статья:

⚪UX-редакторам в растущих продуктах, где нет правил написания текстов и редполитики,

⚪UX-редакторам, которые пришли в давно живущий продукт без налаженных текстов и голоса (англ. «Tone of Voice»),

⚪команде UX-редакторов, которые начали или давно ведут редполитику, но пока не договорились, как должен отзываться продукт в разных состояниях,

⚪дизайнерам, которые работают над одним продуктом, но без UX-редактора в штате.

Всем привет! В процессе обновления инфраструктуры сопровождения наших программных решений мы получили интересный опыт, которым хотим поделиться. Эта статья не просто пошаговая инструкция, а практический разбор того, как мы выстроили процесс подготовки технической документации на основе MkDocs Material, автоматизировали его через GitLab CI/CD и встроили полученный результат в сайт на Битрикс. Наш опыт окажется полезным тем, кто хочет навести порядок в документации и сделать её частью полноценного dev-процесса.

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

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

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

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

Привет, я — Таня Кириллова, технический писатель команды развития безопасности контейнеров в 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 и какой.

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