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

В данной статье содержится вольный перевод документации по Structurizr.

Из-за большого объема информация разделена на три статьи:

• общее описание языка;

• синтаксис;

• книга рецептов (эта статья).

В данной статье содержится вольный перевод документации по Structurizr.

Из-за большого объема информация разделена на три статьи:

• общее описание языка;

• синтаксис (эта статья);

• книга рецептов.

В данной статье содержится вольный перевод документации по Structurizr.

Из-за большого объема информация разделена на три статьи:

• общее описание языка (эта статья);

• синтаксис;

• книга рецептов.

В какой-то определенный момент после старта нового проекта, когда «временный» MVP почти готов, весь интересный код уже написан, пакеты еще свежие и обновляются, команды начинают замедляться в Time to Market.

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

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

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

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

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

С тех пор строители не оставили попыток обойти древнее проклятие и найти подходящий способ объяснить свои ожидания от объекта строительства.

В книге «Руководство BIMcert — Базовые сведения openBIM (издание 2023 г.)» Леон ван Берло (Léon van Berlo), технический директор BuildingSMART International, и Симон Фишер (Simon Fischer), ассистент университета в области исследований цифрового строительного процесса Венского технического университета в Главе 3.7. объясняют, какие перспективы строительной отрасли даёт стандарт IDS. Рассмотрены примеры использования данного стандарта при формировании требований к автоматизированному обмену сведениями компонентов модели.

«Руководство BIMcert — Базовые сведения openBIM (издание 2023 г.)» доступно для бесплатной загрузки по адресу https://www.buildingsmart.co.at/downloads

3.7. Регламент передачи информации
3.7.1. Структура данных
3.7.2. Взаимосвязь со словарем данных buildingSmart
3.7.3. Фасет-параметры
3.7.4 Простые и составные ограничения
3.7.5. Область применения и использование IDS
3.7.6. Новые возможности с IDS
3.7.7. IDS в деталях
3.7.8. Альтернативные варианты
3.7.9. Возможности визуализации IDS
3.7.10. Взаимосвязь IDS с IFC

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

Существует достаточно большое количество нейросетей, генерирующих изображения. Относительно недавно появилась новая версия модели генерации изображений по тексту Kandinsky 3.0 (дальше К3). На носу – масленица Новый Год, поэтому мы с К3 решили нарисовать символ китайского 2024 года, а именно зеленого деревянного дракона. Т.к. показать на рисунке, что дракон деревянный – задача нетривиальная, поэтому решено нарисовать просто добродушного зеленого дракона в стиле цифровой живописи.

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

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

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

Итак, вы готовитесь выпустить в мир IT-продуктов новый классный сервис. Конечно, стоит рассказать вашим пользователям о том, как эта штука работает. Даже к самому простому стулу из IKEA есть инструкция, а ваш сервис, наверняка, посложнее стула. Но по каким-то причинам вы не можете привлечь технического писателя, чтобы он написал инструкцию. Ну что ж, есть и другие варианты.

Технические писатели создают текстовые документы, но что если для процесса одного текста мало? Тогда приходится учиться монтировать и делать видеоинструкции.

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

Должно быть интересно!

Привет. Я занимаюсь продуктовой аналитикой уже довольно давно, и так получилось, что чаще всего в работе мне прилетают именно продуктовые рисёрчи. Иногда нужно разобраться с какой-то фичей, которую никто никогда не изучал, иногда это моделирование перед какими-то изменениями, иногда просто раскопка какой-то проблемы.

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

Тут я хочу поделиться порядком действий, если хочешь — чек-листом, как я провожу аналитические исследования.

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

Однажды мы в documentat.io решили спасти наших техписов от рутинной ручной замены кавычек и написали для них статью про умную автозамену — с использованием регулярных выражений. Теперь решили поделиться ей на Хабре.

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

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

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

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

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

Привет! На связи лид команды аналитиков Magnus Tech Владислава Никитина.

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

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

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

Документация YDB разрабатывается на GitHub рядом с основной кодовой базой YDB и автоматически публикуется на сайт посредством CI/CD. Быть в курсе что в ней появляется можно с помощью функции «Watch» на GitHub или периодически просматривая вывод команды git log , но эти способы сложно назвать удобными. В этом дайджесте мы рассмотрим основные недавно опубликованные изменения в документации YDB.

Наверняка у многих бизнес-аналитиков есть цель использовать особые артефакты: Impact Map, CJM (Customer Journey Map), USM (User Story Map). Особые, т. к. не так часто они встречаются в бизнес-требованиях, и даже бывалый аналитик может с непривычки растеряться, если не создаёт их каждый день. 

Меня зовут Ирина, я ведущий бизнес-аналитик с более чем пятилетним опытом. Сейчас работаю в X5 Tech в направлении “Цепочки поставок”.

В статье описываю общие принципы построения Impact Map, CJM и USM и вариации их использования не только на примере своих рабочих кейсов, но и на бытовых примерах (буквально на жареной картошке и строительстве дома). Для опытных специалистов разобранные примеры пополнят копилку насмотренности. А для новичков в бизнес-анализе статья будет полезна с точки зрения постижения азов.

Всем привет, меня зовут Мишинёва Екатерина, я – ведущий технический писатель с опытом работы в сфере IT более 10 лет.

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

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

Привет, Хабр! Я работаю техническим писателем в компании documentat.io, мы занимаемся заказной разработкой технической документации, в том числе на английском языке.

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

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