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

У нас в команде два системных аналитика с разным бэкграундом и изначально разными подходами к оформлению требований, в том числе к 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 лет.

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

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

С 2024 года процедура внесение радиоэлектронной продукции в реестр Минпромторга существенно изменится. Об этом говорят два уже прошедших этап обсуждения проекта постановления Правительства. О том какие изменения произойдут и как включить РЭП в реестр Минпромторга расскажу в статье. Про ТОРП читайте отдельно.

Основные изменения в законодательной базе:

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

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

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

Привет! Хочу поделиться парой мыслей о представлении нефункциональных требований в формате User Story. Вы наверняка помните самый распространенный шаблон для историй. В шаблоне есть три части «кто», «хочет что», «чтобы что». Чтобы соблюдать такой формат, важно выделить действующие роли и цели для каждой истории. Для нефункциональных требований это бывает непросто и я часто думаю: «А нужно ли?».

Майк Кон в своем блоге пишет, что нефункциональные требования хорошо ложатся в стандартный шаблон пользовательской истории и что такой шаблон позволяет не забыть, почему это требование появилось. В статье «Нефункциональные требования как пользовательские истории» (Non-functional Requirements as User Stories) приведены кейсы, среди которых есть несколько «синтетические». Например, на мой вкус странно выглядит история вида «Как человек, говорящий на одном из латиноамериканских языков, я, возможно, когда-нибудь захочу запустить ваше программное обеспечение». Как работать с такой историей в бэклоге? Сможет ли команда адекватно ее декомпозировать на атомарные задачи?

Обычно бывает интересно почитать не только саму статью в блоге, но и комменты к ней. В комментариях к статье Майка Кона как раз есть похожие вопросы:

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

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

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

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

Я столкнулся с тем, что я иногда не понимаю код, с которым мне приходится работать. И это сильно сказывается на моей производительности и на качестве конечного результата. Неделю назад я прочитал статью Плохо девелопмент за авторством @dalerank(Сергей Кушниренко), в которой описывается проблема молодых специалистов, которые упрощая себе работу пользовались готовыми решениями, а не писали код с нуля. Моя статья не об этой статье и не ответ к ней. В самой статье Сергея Кушниренко была ссылка на другую статью - You should refuse to develop what you don’t understand. И вот эта статья меня несколько озадачила. Я задумался о проблеме понимания того, с чем я работаю. О ней я бы хотел написать, но и некоторые тезисы из статьи Сергея Кушниренко я тоже затрону.

ВНИМАНИЕ! Дальше вас ждет душная простыня текста без юмора.

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

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

— Видишь суслика?

— Нет…

 — И я не вижу. А он есть!

Одним из мощных и удобных инструментов текстовых редакторов является скрытый текст. Этот инструмент имеется практически во всех редакторах. Самым популярным и совершенным редактором на данный момент является MS Word. Поэтому некоторые возможности скрытого текста рассмотрены на его примере.

Всем привет! Меня зовут Ксения Непомнящая, я — технический писатель в команде Zyfra Mass & Energy Balance (Z-MEB) компании «Цифровая индустриальная платформа». Z-MEB — это продукт для предприятий добычи и переработки нефти, газа и руды, участвующий в программе импортозамещения. Сегодня предлагаю вам взглянуть на пользовательскую документацию как на путеводитель по продукту и рассмотреть ее роль в увеличении ценности продукта.

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

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

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

ArchiMate предоставляет общий и унифицированный способ изображения и анализа архитектур предприятий. Разработанный The Open Group, этот открытый и независимый язык моделирования предлагает визуальное представление отношений между различными компонентами в организации. Язык разработан интуитивно, что делает его доступным как для технических, так и для неспециалистов. Нотация ArchiMate основана на последовательной структуре, что позволяет аналитикам создавать ясные, краткие и стандартизированные модели.