Постарайтесь обойтись без жаргонных и туманных фраз. Не используйте их, если не уверены, что поможете тем самым читателю, что случается крайне редко. Или, говоря более сложным языком, сократите возможную путаницу, возникающую из-за намеренного использования концептуальных вопросов в виде сокращения макропонятий к неоднозначно толкуемым преобразованным понятиям и повсеместной отмены избыточных языковых групп.
Придерживайтесь наработок, содержащихся в старых технических условиях. Если вы застряли, пытаясь получше преподнести концептуальное положение или выразить что-то в виде диаграммы, хорошую подсказку всегда можно найти в старых технических условиях. Если вам попадутся удачные технические условия, написанные кем-то другим, воспользуйтесь ими.
При составлении технических условий постоянно думайте о специфике восприятия тех людей, которые будут все это читать. Даже если команда состоит всего лишь из десяти человек, то наиболее зависимыми в своей работе от технических условий окажутся, скорее всего, четверо или пятеро их них. Прибавьте для разнообразия какого-нибудь толкового знакомого, не состоящего в команде и не знающего той технологии, которую вы используете. Как бы вы объяснили ему вашу малопонятную концепцию?
Не демонстрируйте свою влюбленность в Visio или блок-схемы. Относитесь ко всему доступному инструментарию с платонической любовью. Обычно диаграммы представляют интерес только для их создателя, и зачастую от них значительно меньше проку, чем он себе это представляет. Иногда удачно написанный абзац или набросок дают больше представления, чем UML-диаграмма из 500 блоков. (Лишь то, что диаграмма является единственным средством авторского понимания какого-нибудь положения, не дает никаких гарантий, что ее использование является лучшим способом объяснения этого другим людям.) Но разумное применение инструментария и диаграмм может быть вполне оправдано.
Что это, справочник или технические условия? Вообще-то технические условия не должны быть полным справочником по API-функциям или описанием каждого возможного варианта поведения продукта. Разумнее сосредоточиться на объяснении десяти-пятнадцати наиболее общих или важных положений и создать отдельный документ с исчерпывающим перечнем всего остального (с меньшей степенью детализации).
Перед тем как с головой уйти в работу, опишите в общих чертах все сложные алгоритмы, воспользовавшись псевдокодом или обычным языком. И, как уже ранее упоминалось, следует учесть, что распределение объяснений по уровням поможет быстрее усвоить материал даже интеллектуалам. Как минимум, важную роль могут сыграть удачно составленные резюме и краткие обзоры.
А вот еще один прием, который всегда представлялся мне полезным: когда кого-то в черновом варианте технических условий что-то смущает (что сразу же обнаружится, стоит вам лишь уговорить кого-нибудь его прочитать), не пожалейте пяти минут на объяснения. Как только до него дойдет суть сказанного, спросите, какой способ лучше избрать для объяснения этого же вопроса в технических условиях. Иногда вы сможете получить дельный совет, а иногда и нет, но ваше понимание вопроса неизменно упростится, поскольку вы сами себя заставите взглянуть на него шире. С каждым обращением к другим людям вы приобретаете несколько иное осмысление конкретного концептуального положения, повышая тем самым шансы отыскать наилучший подход к его объяснению. Если вы заняты составлением технических условий, следует запомнить, что легче всего получить дельные отзывы, если вы сами к этому стремитесь.
Гарантия верного хода процесса
Технические условия определяют ряд намерений и являются основой для следующего утверждения: «Если все пройдет без неожиданностей, то по окончании этой работы мы получим именно то, что описано в документе». Это означает, что все (или почти все, в разумных пределах) в поведении и функционировании, задекларированное в функциональной спецификации, будет обнаружено по окончании работы в финальном варианте работающего кода. Вполне возможно, что на следующий день после завершения работы над техническими условиями в мире могут произойти изменения, а намерения останутся на уровне, который соответствует дню их написания. Мировые изменения, какими бы они ни были, должны найти свое отражение в изменениях и дополнениях к намерениям.
На техническом уровне цель технических условий состоит в том, чтобы сообщить об этих намерениях всем заинтересованным лицам. Для тестировщиков и контролеров качества это означает предоставление достаточно точного описания ожидаемого поведения проектируемого продукта для составления предварительных контрольных примеров и определения оценочных критериев. Маркетологи, составители документации и прочие специалисты, задействованные в проекте, перед тем как приступить к своей работе, могут нуждаться в ответах на другие вопросы, касающиеся конечных результатов. Специалистам по технической поддержке или рекламным агентам для работы по сопровождению продукта или для ее планирования потребуется представление о том, как он будет работать.
Людям, ознакомившимся с техническими условиями, лучше всего задать вопрос: «Получили ли вы все необходимое для того, чтобы выполнить свою работу на самом высоком уровне?» Уделяя внимание читателям, вы измените их заинтересованность. Они начнут задавать куда более дельные вопросы и переведут в своем сознании технические условия в разряд документов, востребованных в их дальнейшей работе.
Кто, когда и как
Как и при составлении концептуальных документов, очень важно, чтобы у технических условий был один автор. Все, кто собирается принимать участие в работе, должны способствовать ее продвижению путем высказывания собственного мнения и подборки содержимого, но фильтровать весь материал, придавать ему форму и собирать все воедино должен один человек. Причина здесь довольно проста: если вы хотите, чтобы технические условия читались, как творение индивидуума со светлой головой, вы не допустите, чтобы составителями различных частей документа были разные люди. Пока этот самый единственный автор понимает, что его работа заключается в объединении всех дельных вкладов и советов, поступающих от всех, кто их предлагает, все будет идти успешно.
Полагая, что главное авторство должно принадлежать одному человеку, лучшими кандидатами на эту роль можно определить руководителя проекта, проектировщика или ведущего программиста. Поскольку составление технических условий предполагает принятие многофункциональных решений, они должны быть написаны кем-нибудь, кто несет наибольшую ответственность за принятие решений на этом уровне. Функциональные и технические спецификации должны соответствовать перечню работ, составленному командой программистов, и иметь с ним обратную связь. Если разработчики и проектировщики действовали в процессе проектирования совместно, то такое соответствие будет вполне естественным результатом. Дополнительные преимущества совместной работы на ранней стадии формирования взглядов на процесс составления технических условий заключаются в том, что планирование действий будет рассматриваться как плодотворное сотрудничество, а не как начало бурных дебатов и разочарований.
