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

Богатый язык инженера - это ещё один способ утвердить свой профессиональный уровень в глазах окружающих.

- Ооо, ты инженер конструктор?

          - Да!

- Скажи что-нибудь как инженер конструктор!

        -Крыльчатка насоса.

- Бог с ним, отправляй, по замечаниям исправим...

Профессия «Инженер» - компактное название с громоздким синтаксисом и семантикой. Благодаря труду инженеров страны развиваются, а население выходит на новый уровень жизни. Каждый из нас хоть раз восторгался видом чего-то нового – например, ракеты или новой машины. Мы путешествуем в разные страны, в том числе, с целью посмотреть на технические выставки и развитие стран, то есть, на работу инженеров. Однако за каждым открытием и творением стоит ни с чем не сравнимый труд. И в каждом открытии и творении стоит инженерная мысль, возможно, уникальный проект инженера.

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

Как же сделать ТЗ понятнее? Можно улучшить текст — вместо скупого текста составить вариант использования. А можно использовать визуализацию. То есть добавить в требования картинки, диаграммы, таблицы...

Причем сделать это может не только аналитик, но и любой член команды. Тестировщикам особенно полезно визуализировать ТЗ, потому что это помогает сразу увидеть проблемные места и уточнить их ещё до реализации. Раннее тестирование и всё такое =)

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

В заголовке использовано слово сложной, под которым можно понимать все, что угодно. Утверждение о том, что 2 * 2 = 4, если вдуматься, тоже очень не просто. Но в данном случае всё банальнее. Речь идёт о ЕСКД, ГОСТ, ОСТ и тому подобных скучных терминах, отягчаемых бюрократической процедурой согласования.

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

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

Пройдя определённую боль, мы с коллегами решили ей поделиться.

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

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

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

State & Transition Diagramm (сокращенно S&T) — схема состояний и переходов. Техника для визуализации ТЗ. Она наглядно показывает, как некий объект переходит из одного состояния в другое.

Вот объект находился в состоянии А, потом произошло какое-то действие, и он попал в состояние В. Потом он попадет в состояние С и другие... Принцип не меняется, было одно состояние, стало другое.

Поговорим о том, какие инструменты хотелось бы иметь при описании бизнес-процессов. Инструментов BPMS (BPM systems) много, но выбрать то особо нечего …  

Ниже перечислим некоторые важные инструментальные возможности некоторых сред моделирования процессов (в основном ARIS и MS visio).

Decision Table (таблица решений) — техника, помогающая наглядно изобразить комбинатору условий из ТЗ.

Чем проще и понятнее требования, тем меньше будет разночтений. И тем меньше исправлений после реализации. И тем проще нам, тестировщикам, писать тест-кейсы по таким требованиям.

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

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

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

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

Разработчику с проектированием и документированием решения задачи помогает аналитик.

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

Вот только на что обращать внимание при тестировании? Есть набор основных характеристик, которыми должна обладать хорошая документация:

Наверняка многие, желая создать интернет-магазин, сталкивались с вопросами. Выгодно ли? Насколько трудно создать? Сколько стоит? Какие подводные камни? Давайте попробуем разобраться.

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

Однако помимо ТЗ есть еще куча другой документации, которую тоже стоит проверить. Как минимум вычитать, нет ли ошибок. Давайте посмотрим, какая бывает документация:

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

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

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

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

Мы решили продолжить наш цикл статей про разработку пользовательской документации, но на этот раз нам захотелось рассказать об еще одном способе создания инструкций для пользователей — это съемка видеороликов. Мы расскажем о процессе их производства: от возникновения идеи до загрузки ролика на YouTube-канал. У нас нет студии и профессиональных актеров, мы все делаем сами и хотим показать вам, что это не так сложно. Здесь вы найдете: идеи, готовые алгоритмы и, быть может, вдохновитесь на съемку своей видеоинструкции.

Бенчмарк для технологии манипуляции

• если значение меньше единицы, то применение РТК для измеряемой задачи обладает меньшей эффективностью по сравнению с использованием человеческого труда.
• если больше единицы, то применение РТК более эффективно по отношению к использованию ручного труда.

Бенчмарк эффективности решения задач манипуляции предметами (MPE)

Назначение: Бенчмарк предназначен для оценки эффективности применения робототехнического комплекса в практических задачах манипуляции предметами по сравнению с другими системами автоматизации (в т.ч. роботизации) или использованием ручного человеческого труда.

Разработано: Лаборатория робототехники Сбера

Внимание! Если вы перешли сюда по ссылке из поисковой системы!

Корректная ссылка на статью: https://habr.com/ru/post/534954/