Спецификации должны быть занимательными

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

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

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

Из книги Джоэла Спольски «Джоэл о программировании» (2008), глава 8-я «Безболезненное составление функциональных спецификаций».