Скотт Беркун - Искусство управления IT-проектами

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

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

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

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

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

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

Не демонстрируйте свою влюбленность в Visio или блок-схемы.Относитесь ко всему доступному инструментарию с платонической любовью. Обычно диаграммы представляют интерес только для их создателя, и зачастую от них значительно меньше проку, чем он себе это представляет. Иногда удачно написанный абзац или набросок дают больше представления, чем UML-диаграмма из 500 блоков. (Лишь то, что диаграмма является единственным средством авторского понимания какого-нибудь положения, не дает никаких гарантий, что ее использование является лучшим способом объяснения этого другим людям.) Но разумное применение инструментария и диаграмм может быть вполне оправдано.

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

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

А вот еще один прием, который всегда представлялся мне полезным: когда кого-то в черновом варианте технических условий что-то смущает (что сразу же обнаружится, стоит вам лишь уговорить кого-нибудь его прочитать), не пожалейте пяти минут на объяснения. Как только до него дойдет суть сказанного, спросите, какой способ лучше избрать для объяснения этого же вопроса в технических условиях. Иногда вы сможете получить дельный совет, а иногда и нет, но ваше понимание вопроса неизменно упростится, поскольку вы сами себя заставите взглянуть на него шире. С каждым обращением к другим людям вы приобретаете несколько иное осмысление конкретного концептуального положения, повышая тем самым шансы отыскать наилучший подход к его объяснению. Если вы заняты составлением технических условий, следует запомнить, что легче всего получить дельные отзывы, если вы сами к этому стремитесь.