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

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

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

- мощности и производительности

- безопасности, соответствию стандартам и законодательству

- переносимости и совместимости.

Всем, кто создавал библиотеки или сервисы с публичным API хорошо знакома боль, когда документация отстает от изменений в коде и рутинный процесс обновления документации на сайте становится настолько неинтересным, что про него просто забывают. Можно ли как-то автоматизировать генерацию технической документации (а в идеале еще и создание руководства пользователя с возможностью навигации и красивыми картинками)? В этой статье мы обсудим возможности Dokka (Kotlin-инструмента для создания документации) и подходы к генерации артефактов документации с использованием плагинов Gradle.

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

Привет! Это Теодора — технический писатель Платформы, жизненно важного департамента Ozon. Документация для нас имеет большое значение, потому что вся компания пользуется нашими разработками: инфраструктурой as a service; фреймворками и библиотеками; инструментами для работы с базами данных и аналитикой и прочим. Сотни инженеров ежедневно обращаются к нашим сервисам и нуждаются в их описании.

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

Недавно я сменил работу и, как все новички, столкнулся с трудностями адаптации на новом месте. Предыдущие 5 лет я работал в одной компании и выступал стороной, принимающей людей в команду. И вот мне довелось побывать на их месте.

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

Всем привет, мы – Таня и Лиза, системные аналитики в МТС. В этой статье мы поделимся опытом внедрения структурированного шаблона функциональных требований (ФТ) к разработке ПО в нашей команде.

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

Добро пожаловать под кат!

Привет, Хабр! Меня зовут Юрий Никулин, и я руководитель направления документирования Cloud. Сегодня расскажу, как мы перешли с документирования в Word на подход docs as code и почему в качестве языка разметки выбрали reStructuredText.

Как попасть в Реестр отечественного ПО Минцифра? Зачем? И причем тут пользовательская документация.

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

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

Например, что делать если во время звонка мы захотим показать клиенту корпоративный номер его персонального менеджера, даже если менеджер использует свой личный телефон? Ответить на этот вопрос нам поможет Telecom API от компании MTT: компания-клиент МТТ настраивает переадресацию с выделенного оператором связи номера на личный номер менеджера. При этом клиент контролирует все коммуникации, а личный номер менеджера остаётся под защитой при обратном звонке благодаря переадресации на номер компании-клиента МТТ.

Но скучно будет просто написать обзор API, поэтому мы еще сделаем свой собственный “зародыш CRM” с помощью моей любимой XWiki, щепотки кода и Telecom API.  На всё это у нас уйдет буквально 10 минут. 

Сегодня мы с вами: 

- посмотрим как решить проблему защиты номера звонящего с помощью API callback вызова и управления входящим вызовом; 

- сделаем свое расширение для open source вики-движка XWiki и интегрируем в него методы callback вызова, чтобы звонить прямо из XWiki.

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

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

В рамках своей работы и ведения подкаста по бизнес-анализу (ссылка на подкаст), я часто получаю вопросы от бизнес-аналитиков. И один из самых частых - как задокументировать нефункциональные требования, если на проекте принят стандарт написания пользовательских историй? Сегодня, я хотела бы поделиться переводом статьи Майка Кона, о том, как описать нефункциональные требования с помощью пользовательских историй.

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

Одна из самых частых проблем при миграции информационных систем на ОС Astra Linux — это искажение документов, ранее созданных на ОС Windows в MS Office и других программных средствах. В лучшем случае «слетает» вёрстка, в худшем — всё превращается в текст из нечитаемых символов, известных в народе как кракозябры.

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

Всем привет.

Меня зовут Саша, я технический писатель в CSI, но занимаюсь и проектами в нашей команде разработки. Считайте, что сегодня вы зашли ко мне на работу, плюхнулись в пуфики, взяли кофе — и я просто так рассказываю вам про наш портальчик. Всю публичную техническую документацию по ИТ-продуктам компании мы ведем на портале поддержки, который развернут в инстансе Atlassian Confluence Cloud. Расскажу, как мы к этому пришли, как работали над структурой и принципами подготовки материалов, какой от этого профит.

Картинка тут не случайно. Буквально вчера знакомый художник прислал мне такой портрет меня — и я подумал, что она тут в тему: думаю, многим знакома ситуация, когда в одной голове или ресурсе сосредоточены все знания. Это про меня. Но сейчас я с вами с удовольствием поделюсь!

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

В этой статье я опишу примеры подобных ситуаций и расскажу о техниках, позволяющих задать нужные вопросы, выявить максимальное количество требований на ранних этапах анализа, обсудить со стейкхолдерами нужность этих требований и их приоритеты. Как правило, после применения всех техник в 1,5−2 раза возрастает объём требований и юзкейсов для обсуждения — и это одна из основных задач аналитика: задать все вопросы и выяснить все детали до начала проектирования и разработки системы.

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

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

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

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

Все это сложный и трудоемкий процесс. Вы сможете выполнять эти задачи эффективнее с помощью Таблицы принятия решений (Decision table) из состава нотации Decision Model and Notation (DMN).

Я, Lead BA , сертифицированный бизнес-аналитик от IIBA и системный аналитик от IREB, имеющий 14-летний стаж работы в ИТ, хочу поделиться с вами своим опытом использования Таблицы принятия решений (Decision table).

Язык Python (правильно это читается "Пайтон", но в русскоязычном сообществе так же прижилось и прочтение "Питон", мне оно тоже больше по душе ;) в последнее время получил очень большую популярность в среде непрограммистов по двум причинам:

- лёгкий синтаксис, очень близкий к естественным языкам и математическому мышлению;

- огромное количество различных библиотек (модулей), написанных как на самом питоне, так и на более быстрых языках С/С++ и Фортран.

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

Один из вариантов решения этой проблемы — сделать реверс-инжиниринг запасной детали. Иными словами, взять имеющуюся деталь, снять с  нее размеры, определить материал, покрытие, термообработку, выпустить чертеж. С  таким чертежом можно уже обращаться на  производственные предприятия. Алгоритм понятный, но  давайте попробуем посмотреть детально на  проблемы, с которыми можно столкнуться.

В Альфа-Банке мы уже больше 5 лет ведём документацию рядом с кодом. Но она используется не для всех проектных документов. Дело в том, что документация у нас делится по слоям: фронт, миддл и бэкенд. Если с миддлом — слоем микросервисов — всё хорошо, то вот с переводом фронт- и бэк-документации в Bitbucket возникает трудность в необходимости хранения бинарников с примерами пользовательского интерфейса. 

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

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