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

Скиллы и компетенции аналитиков в данной статье описаны в срезе компании, занимающейся аутсорс‑разработкой. Это накладывает определенные требования к аналитикам, так как им за частую приходится участвовать в проектах с разными стеками технологий и доменами. Что в свою очередь требует широкой эрудиции и умения быстро разбираться в новых предметных областях и технологиях. Ниже приведены требования к каждому грейду для бизнес‑аналитиков (BA) и системных аналитиков (SA), с акцентом на их отличия. Учтены ключевые компетенции (SQL, Python, бизнес и системный анализ, UML, BPMN, интеграции, брокеры сообщений, микросервисная архитектура, базы данных), софт скиллы (усиливаются с ростом грейда), опыт работы (основной фактор грейда) и требования, продиктованные аутсорсинговой спецификой.

В моей предыдущей статье Запахи технической документации я писала про схожесть применяемых способах познания программирования по отношению к документации. Что я сделаю сейчас? Совершенно то же самое. Напомню, что шаблоны проектирования описывают типичные способы решения часто встречающихся проблем при проектировании программ. Рассмотрим шаблоны проектирования, представленные на ресурсе Refactoring Guru (сейчас он запрещен на территории РФ). Ну, что, начнем?

Авторы: Бобов Д., Красильников Н.

Оглавление

Введение.

Исходные принципы построения кода.

Лексическая структура кода и допустимые символы.

Группа 3. Кодирование функциональных, строительных подсистем или зон.

Кодирование помещений.

Группа 4. Кодирование агрегатов.

Особенности нумерации агрегатов.

Пример кодирования агрегата.

Группа 2. Код здания, сооружения или территории.

Группа 1. Код местоположения и площадки объекта (site, plant).

Правила кодирования инфраструктурных сетей.

Правила кодирования автодорог и других инфраструктурных путей.

Правила кодирования распределённых технологических систем (расположенных в разных зданиях или сооружениях, но представляющих единую систему)

Кодирование Работ.

Кодирование Документов.

Иерархическое представление закодированных позиций.

Рекомендации по маркировке закодированных позиций.

Заключение.

Уже второй год подряд мы (documentat.io) проводим опрос среди русскоязычных технических писателей. 

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

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

Привет! Меня зовут Аня Салугина, я технический писатель в Ozon Tech. Наша команда готовит и актуализирует документацию для покупателей, продавцов, партнёров, разработчиков и сотрудников Ozon. Недавно мы решили, что хотим улучшить наш стайлгайд и сделать его публичным.

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

Спойлер: командная работа — ключ к успеху.

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

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

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

Как команда платформы, которая помогает техническим писателям управлять документацией без головной боли, мы каждый день видим, как сложные проекты превращаются в понятные руководства, API-доки — в четкие инструкции для разработчиков, а запутанные процессы — в прозрачные чек-листы. И знаем, что техническое письмо — это не только шаблоны, ГОСТы, версионный контроль и так далее. Это еще и ясность формулировок, логика повествования, эмпатия к тем, кто будет читать ваш текст.

Даже самые крутые инструменты (вроде Документерры) не могут вложить эти навыки в писателя. Но мы можем предложить список для чтения ;) 

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

Читайте подборку, сохраняйте в закладки, делитесь, чем еще дополнить список — и давайте делать мир документации лучше вместе!

Привет, дорогие читатели Хабра! С вами на связи Алина Шилова, старший аналитик направления разработки цифровых продуктов T2. Я занимаюсь системным анализом уже не первый год и хочу признаться, что за время своей работы нарисовала какое-то чудовищное количество диаграмм. Ведь все мы, аналитики, призваны нести в мир эту магию кубиков и стрелочек.

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

Конкретика и практичность — залог успешной миграции из Confluence. Разбираем основные ошибки, которые могут осложнить процесс: от неподготовленных данных до неправильно организации миграции. Делимся советами по организации данных, выбору оптимальных решений и способам минимизации рисков утраты информации.

Исправить опечатку в документации занимало 5 минут компиляции. Страницы с картинками загружались медленно.

Я считаю, чтобы посмотреть документацию не нужен JavaScript. Расскажу как переехал с docusaurus + react на starlight + astro и оптимизировал сайт под экологию.

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

Magnit Tech не стал исключением, ведь я пришла в команду, которую только-только сформировали. То есть – ни одной странички в Confluence в нашем разделе.

Звучит пугающе? А меня это заинтересовало. Так что, в этой статье я расскажу:

Зачем –> определение конечной цели
Кому –> распределение ответственности
О чем –> выбор темы для документации
Когда –> выбор времени для написания
Как –> эффективное донесение информации.

А также поделюсь двумя вариантами подхода к написанию документации + как работать над стилистическим оформлением.

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

Ремонт программы на скорости 100 запросов в секунду - это крайне опасная и практически невозможная задача.

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

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

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

Хабр, привет! На связи коллективный разум технических писателей компании «Базис». Над представленным в этой статье проектом мы работали вместе, так что и рассказывать о нем будем вместе. Если точнее, расскажем о том, как познавали методологию Docs-as-Code, зачем техническим писателям дружить с DevOps-инженерами, а главное, почему мы перешли от reStructuredText к AsciiDoc и что нам это принесло.

Большинство гайдов по программному обеспечению написаны трагически плохо.

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

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

Привет! Меня зовут Павел Астахов, я работаю в департаменте системного анализа SM Lab. Сегодня расскажу про проектировочную документацию и её стандартизацию в нашей компании.

Причины внедрения стандартизации

Причина 1. Сотрудники

Департамент системного анализа появился в 2020 году: на тот момент нас было 50 человек в 20 командах; к 2024 году мы сильно разрослись и нас стало уже 260 системных аналитиков, которые трудились в 85 командах. Рост и увеличение масштаба департамента выявили проблемы, которые ранее не были видны и постепенно стали выходить на первый план.

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

Всем привет!

Сегодня хочу затронуть холиварную тему: как сделать диаграмму BPMN немного читабельнее и как избежать логических ошибок. Мы рассмотрим несколько «проблемных» BPMN‑диаграмм, с которыми я встречался в своей практике, и узнаем, как их можно улучшить.