Почему важно написание документации по дизайну программного обеспечения

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

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

*Примечание:* Здесь я описываю небольших клиентов, которым нужна армия из одного человека от их разработчика. Это не единственный путь, по которому может пойти фрилансер, и это не единственные клиенты, с которыми мы работаем в Toptal, но этот путь мне нравится больше всего. Конечно, если вы работаете в команде, а не в одиночку, некоторые из приведенных ниже правил неприменимы. Например, если вы используете методологию Agile или Scrum, вы, вероятно, захотите структурировать свои вехи немного по-другому.

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

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

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

Итак, когда вы беретесь за новый проект, еще до того, как вы откроете Xcode или Visual Studio, у вас должны быть четкие и согласованные цели проектирования . И эти цели должны быть установлены в документе спецификации. Если клиент еще не написал его, вы должны написать его и отправить ему на рассмотрение еще до того, как вы откроете свою IDE. И если вы встретите клиента, который откровенно скажет: «У нас нет времени на проектную документацию», вам следует отказаться от проекта , потому что у вас впереди проблемы. Спецификация не должна быть особенно длинной; это может быть всего несколько страниц, но, по крайней мере, он должен отображать пользовательский интерфейс, включать каркасы (если есть компонент пользовательского интерфейса) и устанавливать этапы завершения.

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

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

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

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

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

Пользовательский интерфейс

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

Прежде чем вы начнете писать код для этих иллюстраций, вы должны ответить на все эти вопросы. В частности, вы должны знать:

1. Всегда ли элементы управления видны и/или включены? При каких условиях изменяются их состояния?
2. Похоже на растровое изображение — это кнопка?
3. Какие переходы происходят между этими состояниями и представлениями? И как их анимировать?

Если вам нужно сгенерировать пользовательский интерфейс для согласования с клиентом, сделайте то же самое в обратном порядке: используйте инструмент каркаса и создайте полный набор макетов экрана, включая любые варианты, которые отображаются в представлениях в разных состояниях приложения. Это может быть утомительной и утомительной работой, но вы не пожалеете об этом — она может уберечь вас от переписывания огромного количества кода и повторного создания интерфейсов из-за незначительного недоразумения с серьезными последствиями. Если вы создаете двойное приложение (например, для iPhone и iPad), создайте отдельные каркасы для обоих.

Размеры экрана тоже важны. Существует (на момент написания статьи) три размера экранов iPhone. Отдельные каркасы для 3,5-дюймовых и 4-дюймовых экранов, вероятно, избыточны, но вам, возможно, придется их сделать; в большинстве случаев можно просто изменить пропорции.

Если ваш клиент предоставляет вам графику, убедитесь, что она имеет правильный размер с правильным соотношением сторон; преобразование любого растрового изображения, содержащего текст или объекты (например, круги), приведет к искажению. Если они не совпадают, попросите клиента создать их заново с соответствующими размерами. Не думайте, что вы можете растянуть 3,5-дюймовую заставку в 4-дюймовую заставку и просто крутить ее.

Функциональность

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

• Что делает приложение и как быстро оно это делает?
• Каковы возможные условия отказа и как они обрабатываются?
• Какие разовые операции выполняются при первом выполнении (т.е. после установки)?
• Если пользователь создает записи любого типа (например, закладки), каковы ограничения?

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

Вехи

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

Пример спецификации дизайна программного обеспечения

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

Заявление о целях

Включите короткий абзац, описывающий проект и его целевую аудиторию.

Функциональное описание

Что делает приложение ? С какими состояниями приложения (высокоуровневые описания основных пользовательских сценариев) столкнется пользователь?

Например, ваше функциональное описание может выглядеть так:

• Первый забег
• Создание Нового _____ (игра, поиск и т.д.)
• Операции
• Поведение фона и переднего плана

Пользовательский интерфейс

Включите каркасы для каждой страницы с подробным описанием:

• Каждый элемент управления, включая состояния (включено/отключено/выделено) и операции.
• Поддерживаемые ориентации и переходы между ними.
• Представленный функционал.
• Обработка ошибок.
• Размеры и ограничения.

Вот каркасы, связанные с моим последним приложением для iOS, NotifEye:

Если вам интересно, я сделал эти мокапы, используя инструмент Balsamiq для создания каркасов.

Например, описание вашего пользовательского интерфейса может выглядеть так:

• Панель навигации
  • Левое управление навигацией: вернуться на домашнюю страницу
  • Строка заголовка: текущий экран или название операции
  • Новая кнопка: создать новую вещь
• Табличный вид
  • Раздел 0: Название раздела
  • Раздел 0 строк:
    • Элемент управления строкой 0 (например, изображение)
    • Текстовая строка 0
    • Текстовая строка 2

Вехи

Как описано выше, сроки завершения и ожидаемые результаты.

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

1. Фасадное приложение, показывающее экран и временные переходы, а также примеры изображений/текста
2. Протокол связи: приложение подключается к сети/серверу
3. Функциональная веха 1: …
4. Альфа-приложение (с полным функционалом)
5. Стабильность
6. Выпускать

Убедитесь, что документация по программному обеспечению остается актуальной

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

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

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

1. Над чем только что работал разработчик?
2. Над чем сейчас работает разработчик?
3. Над чем дальше будет работать разработчик?