Спецификации малой кровью - часть 4: Советы

From The Joel on Software Translation Project

Jump to: navigation, search

Contents

Спецификации малой кровью – часть 4: советы

Джоэл Спольски

Воскресенье, 15 октября, 2000

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

Наибольшие жалобы, которые можно услышать от команд, которые пишут спецификации, заключаются в том, что «их никто не читает». Когда никто не читает спецификации, люди которые их пишут, становятся немного циничными. Это похоже на старый мультфильм Дилберт, в котором инженеры используют стопки из толстых четырехдюймовых спецификаций, чтобы расширить свои рабочие места. В вашей обычной большой бюрократической компании все месяцами пишут скучные спецификации. А когда спецификация закончена, её ставят на полку, с которой больше никогда не берут, и продукт вводится в эксплуатацию с нуля, при этом не рассматривается то, о чем говорится в спецификации, потому что никто не читает спецификацию, потому что она ужасно скучная. Сам процесс написания спецификации может быть хорошим упражнением, потому что он заставляет каждого, по крайней мере, задуматься над проблемами. Но тот факт, что спецификацию, будучи законченной, ставят на полку (непрочтенную и нелюбимую), заставляет людей относиться к написанию спецификации как к пачке бесполезной работы.

К тому же, если вашу спецификацию никто не читает, вы получаете множество споров, когда законченный продукт вводится в эксплуатацию. Некто (менеджер, маркетолог, или покупатель) говорит: «минуточку! Вы обещали мне, что там будет пароварка для моллюсков! Где пароварка для моллюсков?» И программисты говорят, «нет, вообще то, если вы посмотрите в спецификации в главе 3, разделе 4, абзаце 2.3.0.1, вы увидите, что там ясно написано ‘никаких пароварок для моллюсков.’» Но это не удовлетворяет покупателя, который всегда прав, и сердитым программистам приходится изобретать пароварку для моллюсков (что делает их еще более циничными по отношению к спецификациям). Или менеджер говорит, «эй, все формулировки в этом диалоге слишком многословны, и над каждым диалоговом окном должна быть реклама.» И программисты с расстройством говорят, «но вы одобрили спецификацию, в которой было строго описано расположение и содержимое каждого диалогового окна!» Но, конечно, менеджер на самом деле не читал спецификацию, потому что, когда он попытался, его мозг начал просачиваться через глазницы, и, кроме того, это пересекалось с его игрой в гольф каждый вторник.

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

Хорошая манера письма сама по себе заставляет людей читать. Но это будет нечестно с моей стороны просто сказать «будь хорошим писателем» и оставить все как есть. Здесь четыре простых правила, которые необходимо соблюдать, чтобы заставить людей читать ваши спецификации.

Правило 1: Будьте забавными

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

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

  • Пользователь нажимает Ctrl + N, чтобы создать новую таблицу служащих и начинает вводить имена служащих.

напишите что-нибудь такое:

  • Мисс Пигги, тыкая клавиатуру карандашом для подведения глаз, потому что её толстые маленькие пальцы не в состоянии нажимать отдельные клавиши, нажимает Ctrl + N, чтобы создать новую таблицу своих возлюбленных и заносит в неё запись «Кермит».

Если вы почитаете Дэйва Барри, то вы узнаете, что самый лёгкий способ быть смешным заключается в том, что нужно быть конкретным там, где это необязательно. «Мопсы Скреппи» смешнее, чем «собаки». «Мисс Пигги» смешнее, чем «пользователь». Вместо того, чтобы говорить «особые интересы», говорите «фермеры-левши, выращивающие авокадо». Вместо того, чтобы говорить «Люди, которые отказываются убирать за своими собаками, должны быть наказаны», говорите, что они должны быть «отправлены в тюрьмы, в которых так одиноко, что заключенные должны платить паукам за любовь.»

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

Правило 2: Написание спецификации – это как написание исполняемого кода для мозга

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

Когда вы пишите код, ваша целевая аудитория – компилятор. Да, я знаю, что людям тоже приходится читать код, но это очень тяжело для них. Большинству программистов достаточно тяжело привести код к такому виду, при котором компилятор его читает и правильно интерпретирует; заботясь при этом об удобочитаемости кода. Напишите ли вы:

void print_count( FILE* a, char * b, int c ){
     fprintf(a, "there are %d %s\n", c, b);}
main(){ int n; n = 10;
print_count(stdout, "employees", n) /* код преднамеренно запутан*/ }

или

printf("there are 10 employees\n");

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

Зададим функцию AddressOf(x), которая определена как отображающая соответствие между пользователем x и соответствующим ему email адресом RFC-822 в виде ANSI строки. Давайте зададим пользователя A и пользователя B, причем пользователь A хочет послать email пользователю B. Таким образом, пользователь A инициирует посылку нового сообщения, используя любую (но не все) из методов, определенных где-то в другом месте, и печатает AddressOf(B) в окне редактирования To:.

А можно было написать так:

Мисс Пигги хочет пойти пообедать, она пишет новый email и печатает адрес Кермита в окне "To:".

Техническая заметка: адрес должен быть стандартным Internet адресом (RFC-822 совместимым.)

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

Ошибка в том, что, когда вы пишите спецификацию, вдобавок к корректности она должна быть еще и понятной, что в программистских терминах означает, что она должна быть написана таким образом, чтобы человеческий мозг смог ее «скомпилировать». Разница между компьютером и человеческими мозгами заключается в том, что компьютер может сидеть и ждать, пока вы продекларируете переменные, которые будете потом использовать. Но люди не поймут, о чем вы говорите, если их сначала не мотивировать. Люди не хотят, чтобы им приходилось что-либо декодировать, они хотят прочитать все по порядку и понять. Людям необходимо сначала обрисовать картину в общем и лишь потом вдаваться в детали. При написании компьютерных программ вы идете сверху вниз, описывая детали по ходу написания. Компьютеру не важно, содержат ли смысл имена ваших переменных. Человеческий мозг воспринимает гораздо лучше, если с помощью истории нарисовать в нем яркую картину, даже если это лишь фрагмент истории, потому что нашим мозгам свойственно понимать истории.

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

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

Правило 3: Пишите как можно проще

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

Люди используют такие слова как «утилизировать», потому что они думают, что слово «использовать» выглядит непрофессионально. (Снова это слово – «непрофессионально». Всякий раз, когда кто-то говорит вам, что вы не должны чего-либо делать, потому что это «непрофессионально», знайте – у них просто кончились настоящие аргументы.) На самом деле, я думаю, что многие люди считают, что, когда все ясно написано, что-то не так.


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

Избегайте стен из текста: целые страницы одного текста. Люди пугаются и не читают их. Когда вы в последний раз видели популярный журнал или газету, в которых есть страницы одного только текста? Журналы пойдут на то, чтобы взять цитату из статьи и напечатать ее посередине страницы гигантским шрифтом только для того, чтобы избежать страниц одного текста. Используйте нумерованные списки или списки с маркерами, картинки, графики, таблицы, и много свободного места, чтобы чтение «выглядело» более воздушным.

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


 

Ничто так не улучшает спецификацию как скриншоты. Картинка может стоить тысячи слов. Каждый, кто пишет спецификации для программного обеспечения Windows, должен купить копию Visual Basic, и научиться использовать ее хотя бы для того, чтобы создавать макеты экранов. (Для Mac используйте REAL Basic; для Web страниц - Front Page или Dreamweaver). Затем зафиксируйте эти скриншоты (Ctrl+PrtSc) и вставьте их в свою спецификацию.

Правило 4: Просматривайте и перечитывайте несколько раз

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

Я сэкономил много времени, благодаря тому, что не объяснял правило 4, и поэтому добавлю еще одно правило.

Правило 5: Шаблоны нужно избегать

Избегайте соблазна сделать стандартный шаблон для спецификаций. Вначале вам может показаться, что важно, чтобы «все спецификации выглядели одинаково». Подсказка: это не так. Что это вам дает? Разве все книги на вашей книжной полке выглядят одинаково? Вы хотите, чтобы они все выглядели одинаково?

Более того, если вы используете шаблоны, может случиться так, что вам придется добавить кучу разделов к шаблону для вещей, которые вы считаете важными для описания каждой особенности. Примиер: Большой Билл(1) постановил, что с этого времени каждый продукт компании Microsquish должен включать Internet компоненту. Теперь в шаблоне спецификации есть раздел «Internet компонента». И когда кто-нибудь будет писать спецификацию, не важно на сколько простую, ему придется заполнить раздел под названием «Internet компонента», даже если он пишет спецификацию для клавиатуры Microsquish. ( И вы спрашиваете себя, почему эти бесполезные кнопки для Internet покупок начинают появляться на клавиатурах как грибы).

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

Спецификация – это документ, который вы хотите, чтобы люди прочитали. В этом смысле, она не отличается от очерка в The New Yorker(2) или в студенческой газете. Вы когда-нибудь слышали о профессоре, который давал бы шаблоны для студенческих газет? Вы когда-нибудь читали два хороших очерка, которые подошли бы к одному шаблону? Просто выкинете эту мысль.


  1. Haywood, William Dudley (Big Bill) (1869-1928) Хейвуд, Уильям Дадли ("Большой Билл") Деятель рабочего движения. Был пастухом, шахтером. Активист Федерации шахтеров Запада. С 1901 член Социалистической партии, был исключен из состава ее руководства за пропаганду насильственных методов борьбы. Один из создателей (1905) и лидер (с 1908) профсоюзного центра Индустриальные рабочие мира (ИРМ). В 1919 вступил в Коммунистическую партию США. В 1920 был приговорен к 20 годам тюремного заключения по закону о подстрекательстве. Был выпущен под залог и выехал из страны. С 1921 жил в СССР, работал в Международной организации помощи борцам революции (МОПР). (прим. перев.)
  2. The New Yorker — американский еженедельник, публикующий репортажи, комментарии, критику, эссе, художественные произведения, юмор, комиксы и поэзию. Публикуется примерно раз в неделю (47 номеров за год). Издаётся с 1925 года. (прим. перев.)




Автор перевода

Филимонов Вячеслав

vyacheslav.filimonov@auditory.ru



Дополнение

Шкала жёсткости требований к функциональным спецификациям

Personal tools