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

Как обеспечить устойчивое развитие IT-ландшафта под нужды бизнеса и снизить затраты на развитие в горизонте

Изображение от rawpixel.com на Freepik

Когда документация переехала в вики, люди решили, что страницы бесплатные, и начали писать всё в одном документе. Платить в этом случае всё равно приходится, но только не деньгами, а временем и нервами исполнителей, которые эту документацию читают. Я покажу, как разбиваю это на систему связанных страниц, где у каждой — своя роль, а точка входа — одна.

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

Меня зовут Люсьена Мирославская, я работаю техническим писателем в Wildberries третий год. На протяжении развития моей карьеры в IT, а это более пяти лет суммарно в разных компаниях, я часто сталкиваюсь с проблемой недостаточности документации. Её или нет, или она неактуальная, неполная, неверная, да и несистематизированная, а иногда просто непонятная. Я не волшебник, поэтому не смогу вместить весь свой опыт в одну статью, но точно задам направление для ориентира и помогу, как минимум, создать черновик документации.

Проблема: никто не знает, кто кого вызывает

В 2012 году биржевой брокер Knight Capital потерял $460 миллионов за 45 минут.
Причина — активация устаревшего модуля, который начал массово размещать ордера.
Отчёт SEC указал на ключевую ошибку:

Управление строительными проектами и документацией становится проще с системой TDMS Фарватер Web. Для быстрого освоения системы команда «Нанософт» подготовила серию коротких обучающих видео.

Кому это будет полезно? Техническим директорам, руководителям проектов, ГИПам, ГАПам, главным специалистам, проектировщикам, BIM-менеджерам и ИТ-специалистам.

1. Установка и настройка системы TDMS Фарватер Web

От лицензирования до первого запуска. Показываем все ключевые шаги за семь минут. Смотреть видео

2. Как настроить права доступа сотрудников?

Управление уровнем доступа в зависимости от роли (кто и что может делать в системе): от администратора до проектировщика. Смотреть видео

3. Как просматривать файлы из TDMS Фарватер Web?

Работа с документами проекта: просмотр PDF прямо в системе, скачивание и права доступа. Смотреть видео

4. Как создать проект с разбивкой на стадии?

Настройка этапов, объектов и документации. Смотреть видео

5. Как создавать и визуализировать рабочий процесс?

Настройка последовательности согласований, проверок и утверждений позволяет контролировать статус каждой задачи. Смотреть видео

6. Как автоматизировать работу с замечаниями?

Создание замечаний прямо в PDF, их назначение и возврат документов на доработку позволяют контролировать каждую правку и ускорить согласование. Смотреть видео

Бесплатная пробная версия

Оцените все возможности TDMS Фарватер Web на практике – получите бесплатный доступ на 30 дней.

Скачать пробную версию TDMS Фарватер Web

Привет, Хабр, меня зовут Александр Мачулин, я основатель Gramax, open source системы для ведения документации в подходе Docs as Code с визуальным редактором. Gramax хранит контент в git-репозитории. Это означает, что у пользователей могут возникнуть конфликты при синхронизации изменений. Я считаю, что нагружать пользователей решением конфликтов – не очень хорошо и пытаюсь найти решение для этой задачи.

Российские учёные победили болезнь Бехтерева

Научное сообщество и тысячи пациентов по всему миру затаили дыхание: в России было создано первое в мире по-настоящему эффективное средство для лечения анкилозирующего спондилита, известного широким массам как болезнь Бехтерева. Это был не просто новый препарат — это был крах многолетнего приговора, шаг за шагом лишавшего людей подвижности, карьеры и полноты жизни.

Всем привет! Меня зовут Татьяна Цикунова, я работаю системным аналитиком уже более 5 лет и за это время получила опыт в 4 проектах, а также долгое время имела честь онбордить новых аналитиков в разных командах. 

Тема онбординга важна для любого IT-специалиста. Поэтому сегодня разберёмся, как провести онбординг системного или бизнес-аналитика в новую команду не только успешно, но и эффективно.

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

Всем привет! Меня зовут Катя, я развиваю Gramax — базу знаний для it-команд. В этой статье я расскажу, как мы решали довольно очевидную проблему связи знаний и случайно сделали штуку, у которой даже есть отдельное название.

Когда говорят «Semantic Wiki», обычно представляют что-то сложное: онтологии, RDF, графы и так далее. Но можно ли это сделать как-то проще и для людей? В этой статье разберем:

• Что делает вики «семантической».

• Как свойства и представления в Gramax решают эти задачи.

• Как быстро создать семантическую структуру, связать с ее помощью статьи и посмотреть по ним отчеты.

Эта статья для тех, кого волнуют вопросы: качественного ведения базы знаний, создания единого источника правды, построения полезных связей между знаниями (а не банальной линковки, которая побьется через пару релизов).

Сотрудники и студенты Московского Энергетического Института изучили и провели анализ различных способов остановки электрических двигателей, в данном случае мы расскажем вам про метод останова двигателя противовключением.

·         В чем заключается данный метод?

  Данная схема предназначена для быстрой остановки электродвигателя. Она работает таким образом, что, когда мы хотим остановить наш двигатель, вращающийся в одну сторону, мы начинаем вращать его в противоположную таким образом замедляя его движение и приводя к останову. Таким образом противовключение значит, что мы включаем наш двигатель в обратную сторону – в противоположную.

Привет, Хабр! Я являюсь тестировщиком компании TravelLine. Мы разрабатываем единую систему для гостиничного предприятия, которая помогает отелям, санаториям и другим средствам размещения автоматизировать свои бизнес-процессы. В этой краткой статье (я бы назвал её отзывом на инструмент) я не буду рассказывать о концепции встреч в формате “3 Амиго”, хочу лишь поделиться личным опытом внедрения таких сессий в процесс разработки требований в одной из своих команд.

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

Наш воркфлоу выглядел следующим образом:

Как быстро пролетели шесть месяцев! Продолжаю рассказывать о том, как решил сделать пет-проект: НормЦРМ. Сам я ремесленник-одиночка и пользовался ограниченным набором инструментов для ведения дел: Google Таблицы, да Windows-заметки. Решил все эти данные свести воедино в рамках собственной црмки.

Я не разработчик, а проектировщик интерфейсов (UX/UI-дизайнер). Опыта в программировании совсем немного. Поэтому пет-проект был мне особенно интересен. Я уже двадцать лет готовлю проектную документацию для других — а в этот раз для себя.

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

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

В статье бизнес-архитектор Nexign Егор Вершинин рассмотрит, как правильно подготовиться к этому процессу, особенно в условиях жестких сроков и параллельных задач. Его фреймворк поможет выстроить технологию дизайна под конкретный проект, учитывая уровень специалистов и временные рамки. Проверим подход на нескольких примерах по эффективному распределению задач между аналитиками. Надеемся, что этот инструмент станет полезен и вам для оптимизации рабочих процессов и повышения общей продуктивности команды.

Статья получилась большая, поэтому можно сразу сориентироваться по плану:

●      предпосылки и типичные проблемы в командах аналитиков;

●      подготовка к делегированию или масштабированию задач;

●      шаблоны для описания артефактов;

●      технология дизайна;

●      план внедрения технологии дизайна;

●      распределение артефактов по ролям в команде.

Что было интересного в 2025 году по безопасности ИИ? Помимо развития AI-агентов и их протоколов, гардрейлов, и появления фреймворков, для российского рынка важно отметить появление нескольких новых официальных документов. О них и поговорим, так как я искренне считаю, что они выводят нашу нормативно-правовую базу на уровень одной из самых развитый и проработанных в мире. Но этот пост - не просто обзор)
Я расскажу и о своих соображениях о том, как управлять доступом AI-агентов, данными для GenAI-систем, и уязвимостями таких систем.

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

Разработчики видят в документации бюрократию, отвлекающую от настоящей работы. Заказчики и менеджеры — единственную гарантию, что получат то, что просили. Истина, как всегда, посередине. В условиях договорных обязательств документация — это не бумажка, а юридически значимый артефакт, такой же важный, как и сам код.

Давайте разберемся, как сделать ее союзником, а не врагом.

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

Меня зовут Никита Бугуев — я бэкенд‑разработчик на Python в команде, которая разрабатывает открытое банковское API и пытается захватить контроль над всеми интеграциями наружу. В статье расскажу, как мы написали свои велосипеды для вебхуков и какие грабли собрали по пути.

Данный материал создан учеными Национального исследовательского университета "МЭИ" (НИУ "МЭИ") кафедры Автоматизированных систем управления тепловыми процессами (АСУТП). Представленные сведения основаны на результатах исследований и отражают профессиональное мнение авторов.

            Схема пуска и стопа с самоподхватом нужна для того, чтобы при нажатии на кнопку «Пуск» на контакторе, можно было не задерживать эту кнопку. При этом схема продолжит работать, так как контактор подхватил сигнал и теперь напряжение никуда не уйдет, пока не будет нажата кнопка «Стоп». Такая система позволяет надежно и эффективно управлять двигателем.

Лучший способ похоронить базу знаний — это спустить её сверху, обязать всех искать там информацию и бросить в таком состоянии. БЗ только тогда чего-то стоит, когда она вовремя пополняется и актуализируется, когда в ней на конкретный вопрос находится конкретный ответ, когда за информацией не надо бегать по куче ссылок, выискивая крупицы смысла. Когда база знаний не утрачивает своей пользы при росте числа пользователей — как авторов, так и читателей. Только тогда принятие решений на основе знаний будет точным, онбординг новичков будет проходить без задержек, а саппорт будет укладываться в SLA.

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

А вот пользовательская документация живёт куда более сложной жизнью. Её либо не пишут вовсе, надеясь на хороший UX, либо пишут один раз и больше к ней не возвращаются. Через несколько месяцев оказывается, что интерфейс уже другой, кнопки переехали, а скриншоты выглядят как привет из прошлого релиза.

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

Одной из частых задач документирования является документирование баз данных. Это может быть документирование PostgreSQL, Clickhouse, MongoDB и других баз данных. Их все объединяет один простой факт — такую документацию сложно делать вручную. В этой статье я разберу, как создать описание базы данных PostgreSQL с помощью утилиты tbls.