Noveo

Наш блог 9 типичных ошибок в спеках

9 типичных ошибок в спеках

Около года назад мы уже писали о важности ТЗ и некоторых базовых принципах его написания. Однако эту тему смело можно отнести к вечным — сколько бы ни писали рекомендаций по написанию ТЗ, спеки писали, пишут и будут писать как попало. Не все, конечно… но многие :). Вот и Егору Бугаенко надоели очевидные недочеты в спеках, и он попытался просто и понятно объяснить, как избежать хотя бы самых основных. Предлагаем вашему вниманию перевод его статьи:

Есть прекрасная книга “Требования к ПО” авторства Карла Вигерса – собственно, о требованиях к ПО. Я считаю, что она обязательна к прочтению для каждого разработчика ПО. Не вижу необходимости повторять то, что там написано, но все же существует несколько очень простых и очень типичных ошибок, которые мы продолжаем допускать в наших спеках. Я вижу их в наших документах снова и снова, и поэтому решил дать краткий их обзор. Итак, вот они – самые критичные и типичные из них, с точки зрения программиста, читающего спецификацию.

70695

Глава 4.3 известного стандарта IEEE 830-1998 гласит, что хорошая спецификация должна быть безошибочной, недвусмысленной, полной, логичной, упорядоченной, доказуемой, изменяемой и позволяющей отслеживать изменения. Итого 8 качеств. Затем стандарт объясняет их один за другим на очень доступном английском. Но разве у нас есть время читать эти скучные стандарты? Они для университетских профессоров и сертификационных комитетов. Мы же практики! Подождите, я шучу.

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

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

1. Беспорядочная терминология или ее отсутствие

Как насчет чего-нибудь подобного:

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

В чем разница между UUID и номером учетной записи? Это одно и то же? Кажется так, верно? Или, может быть, они различаются… Было бы здорово знать, что же скрывается за сокращением UUID. Это «unique user ID» (уникальный идентификатор пользователя) – или, может быть, «unified user identity descriptor» (единая характеристика идентификатора пользователя)? Без понятия. Я в заблуждении и хочу найти автора этого текста и сделать с ним (или с ней) что-нибудь плохое.

Мы пишем, чтобы быть понятыми, а не впечатлить читателя

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

Вот как этот текст будет выглядеть после хорошего редактирования:

UUID – уникальный идентификатор пользователя, натуральное 4хбайтовое число.
UUID определен по нарастающей, чтобы убедиться, что нет двух пользователей с идентичным номером учетной записи.

Так лучше?

Таким образом, первая и основная проблема – легкомысленное использование терминов и просто слов без предварительного определения их в словаре.

201401202. Вопросы, обсуждения, предложения, мнения

Вот такое я увидел совсем недавно в продуктовой спеке:

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

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

Найдите ответы на все свои вопросы прежде, чем писать документ, именно за это вам платят

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

Спецификации не должны содержать в себе никаких вопросов. Кому эти вопросы адресованы? Мне, программисту? Вы хотите, чтобы я реализовывал ПО или отвечал на ваши вопросы? Мне не интересен брейнсторминг с вами. Я ожидаю, что вы, автор требований, скажете мне, что нужно делать. Найдите ответы на все свои вопросы прежде, чем писать документ. Именно за это вам платят. Если у вас нет ответов, напишите там что-нибудь типа TBD («to be determined», “предстоит определить”). Но не задавайте вопросов. Это раздражает.

Документ с требованиями – не дискуссионный клуб. Как читатель спеки, я ожидаю увидеть, что именно должно быть сделано, безо всяких “может быть” или “мы можем сделать это и по-другому”. Конечно, вам нужно обсудить эти моменты, но сделайте это до того, как вы их задокументируете. Сделайте это где-нибудь в другом месте, в Скайпе, например, или в Слаке, или по электронной почте. Если вы действительно хотите обсуждения в документе, используйте Google Docs или Word с отслеживанием версий. Но когда дискуссия завершена, удалите ее историю из документа. Ее присутствие только вводит меня, программиста, в заблуждение.

160415-168_01

Нет необходимости и в формулировании требований в виде предположений. Просто скажите, что должно быть сделано и как ПО должно работать, не бойтесь оказаться неправыми. Обычно люди прибегают к предположениям, когда они боятся высказать что-то прямо. Вместо того, чтобы сказать “приложение должно работать на устройствах с Android 3.x и выше», они говорят «Я бы предложил сделать приложение совместимым с Android 3.x и выше.» Чувствуете разницу? Во втором предложении автор пытается избежать личной ответственности. Он не говорит «однозначно Android 3.x», он всего лишь предлагает. Не будьте трусом, говорите прямо. Если вы ошибетесь, мы вас поправим.

И, конечно, мнения вообще не в почете. Это не письмо другу; это официальный документ, относящийся к проекту. Через несколько месяцев или недель вы можете покинуть проект, и кто-то другой будет работать с вашим документом. Спека – как контракт между инвестором проекта и проектной командой. Мнение автора документа не имеет здесь никакого значения. Вместо того, чтобы заметить, что “кажется, Java была бы быстрее” и предположить, что “нам следовало бы использовать ее”, скажите “Java быстрее, и мы должны использовать ее”. Очевидно, что вы говорите об этом здесь потому, что так думаете. Но когда это отражено в спеке, нам неважно, от кого пришла эта мысль и что вы думали по поводу этой проблемы. Подобная информация только запутала бы нас, так что опустите ее. Только факты, никаких мнений.

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

Должны быть поддержаны несколько версий API. Как именно это сделано, не имеет значения.

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

Но опять же, повторюсь: спецификация – не дискуссионный комитет.

3. Путать требования к функциональности и к качеству

Вот как это выглядит:

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

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

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

images

Также тяжело изменить подобное высказывание. Если завтра мы добавляем другое функциональное требование – скроллинг списка друзей, например, – мы захотим потребовать, чтобы этот скроллинг также был плавным и быстрым. Затем спустя несколько дней мы захотим сказать, что “быстро” означает время реакции менее 10 миллисекунд. Соответственно, нам нужно будет продублировать эту информацию в двух местах. Видите, каким беспорядочным наш документ может стать в будущем?

Поэтому я бы настоятельно рекомендовал всегда документировать функциональные и нефункциональные требования отдельно.

4. Путать требования и дополнительные документы

Это похоже на предыдущую проблему и выглядит следующим образом:

Пользователь может загрузить PDF-отчет с полным списком транзакций. Каждая транзакция имеет свой ID, дату, описание, счет и итоговую сумму. Отчет также содержит общий итог и ссылку на счет пользователя.

Очевидно, что в этом абзаце описаны две вещи. Первая – пользователь может загрузить PDF-отчет. Вторая – как этот отчет должен выглядеть. Первое – функциональное требование, а вот второе должно быть описано в дополнительном документе (или приложении).

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

download

5. Неизмеряемые требования к качеству

Вот о чем я говорю:

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

Каждая веб-страничка должна открываться быстрее, чем за 500 миллисекунд.

Каждый интерфейс должен быть респонсив.

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

Да, это сложно. Главным образом потому, что замешано много факторов. Возьмем, к примеру, вот эту строчку: “Приложение должно запускаться менее чем за 2 секунды”. На каком оборудовании? С каким количеством данных в профиле пользователя? Что означает “запускаться”; включает ли это в себя время загрузки профиля? Что, если есть проблемы при запуске? Они в счет? И есть еще много подобных вопросов.

Если мы отвечаем на все из них, текст с требованиями займет целую страницу. Никто этого не хочет, но неизмеряемые требования – еще большее зло.

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

navigatsiya-dlya-iphone-luchshie-prilozheniya-e1416234168614

6. Инструкции по имплементации

Этот пример иллюстрирует очень частую типовую ошибку:

Пользователь авторизуется через кнопку “Войти” на Фейсбуке, и мы сохраняем имя пользователя, аватарку и email в базе данных.

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

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

Вы не должны говорить мне, как реализовать функциональность, которую вы хотите

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

Страница с логином должна выглядеть следующим образом (скриншот во вложении).
Мы должны сохранять email пользователя локально для последующих нужд.

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

download-2

7. Недостаток перспективы деятеля

Текст может выглядеть следующим образом:

PDF-отчет генерируется по требованию. Отчет можно скачать или сохранить в своем профиле.

Здесь проблема в том, что не вовлечен “деятель”. Сама функциональность более-менее ясна, только непонятно, кто все это делает. Где пользователь? Это просто история о чем-то, что где-то происходит. Это не совсем то, что нужно разработчику для того, чтобы это имплементировать.

В хороших “пользовательских” требованиях всегда есть… Угадайте, кто?.. Пользователь

Лучший способ объяснить функциональность – это пользовательские требования. И в хороших пользовательских требованиях всегда есть… Угадайте, кто?.. Пользователь. Предложения всегда начинаются с “пользователь…”, за которым следует глагол. Пользователь загружает, пользователь сохраняет, пользователь кликает, печатает, удаляет, форматирует и т.д.

Совершенно необязательно, чтобы пользователь был человеком. Это может быть система, клиент RESTful API, база данных, да что угодно. Но всегда – кто-то. “Можно загрузить” – не пользовательское требование. Можно – кому?

8. Шум

Как насчет чего-нибудь такого:

Больше всего нас интересуют производительность и привлекательный пользовательский интерфейс.

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

Разве хороший программист не сообразит сам, что означает “хорошая производительность”?

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

download-1

Очень часто… Подождите. Очень-очень часто. Нет. Почти всегда. Опять не так. Всегда! Именно, спеки всегда полны шума. В некоторых его чуть поменьше, в других – побольше. Я считаю, что это симптом ленивого и непрофессионального автора документа. В большинстве случаев – просто ленивого.

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

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

9. Будет работать, должно работать

Вот еще одна очень типичная ошибка:

API будет поддерживать JSON и XML. Оба формата должны полностью поддерживать все информационные элементы. XML должен быть подтвержден XSD-схемой.

Видите, как беспорядочно это звучит? Три разных точки зрения, и ни одна из них не подходит для спецификации. Спека должна описывать продукт, как будто он уже существует. Спека должна звучать как руководство, инструкция, справка. Этот текст следует переписать, например, так:

API поддерживает JSON и XML. Оба формата
Полностью поддерживают все информационные элементы. XML подтвержден схемой XSD.

Видите разницу? Все эти словечки “должно” и “будет” только добавляют сомнений в документ. Для читателя такой спеки “API будет поддерживать” звучит как “когда-нибудь в будущем, может быть, в следующей версии, оно будет поддерживать”. Это не то, что автор имел в виду, верно? Не должно быть сомнений, двойных значений, возможности. API поддерживает. Вот и все.

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

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

Если вы нашли ошибку, пожалуйста, выделите фрагмент текста и нажмите Ctrl+Enter.

НазадПредыдущий пост ВпередСледующий пост

Сообщить об опечатке

Текст, который будет отправлен нашим редакторам: