Навеяно статьей из книги “Джоуэл о программировании”
Здесь некоторые советы о том, как писать хорошие тексты и спецификации!
Спецификация — (позднелат. specificatio, от лат. species — род, вид, разновидность и facio — делаю) инженерный термин, обозначающий набор требований или параметров, которым что-то должно удовлетворять.
Чаще всего там, где действительно пишут спецификации, жалуются на то, что их никто не читает. Когда никто не читает спецификации, их авторы становятся несколько циничными. Как на старой карикатуре, где инженеры надстраивают свои кабинки в офисе стопками спецификаций. В типичной большой бюрократической организации все месяцами пишут нудные спецификации. Написав, их отправляют навсегда на полку, а проект делается с нуля и без какой-либо оглядки на спецификацию, потому что ее никто не читал, так как “от нее мозги сохнут”.
Кроме того, когда никто не читал спецификацию, то по завершении paботы над продуктом возникает много споров. Кто-нибудь (из руководства, клиентов или из отдела маркетинга) восклицает: «Погодите, но вы же обещали сделать пароварку для моллюсков! Где она?» А программисты отвечают: «Никак нет, если вы заглянете в главу 3 спецификации, подраздел 4,1 параграф 2.3.0.1, то увидите, что там прямо сказано — никаких пароварок для моллюсков». Но клиент этим не удовлетворяется, поскольку он всегда прав, и разозленным программистам приходится дополнительно оснащать продукт пароваркой для моллюсков (что делает их еще более циничными в отношении спецификаций).
Либо менеджер заявляет: «Послушайте, в тексте этого диалогового окна слишком много слов, а еще в верхней части каждого диалогового окна должна быть реклама». Программисты в отчаянии: «Но ведь вы сами утвердили спецификацию, в которой точно указаны текст и расположение элементов каждого диалогового окна!»
Разумеется, менеджер не читал спецификацию, потому что, когда он попытался это сделать, у него чуть не произошло размягчение мозга, и вообще во вторник он играл в гольф и у него не было времени.
Итак Спецификации вещь хорошая, но только тогда, когда их читают. Если вы пишете спецификацию, то должны сделать так, чтобы ваш труд был прочтен, а также постараться, чтобы скромные остатки чьих-нибудь мозгов не вытекли окончательно из ушей их обладателя.
Чтобы соблазнить людей чтением вашего труда, как правило достаточно написать его хорошим языком. Но будет нечестно, если я скажу «пишите лучше» и на этом покину вас. Вот пять простых правил, которые абсолютно необходимо соблюдать, чтобы ваши спецификации читали.
Правило 1: Пишите занимательно
Да, это первое правило, которое должен соблюдать тот, кто хочет соблазнить людей чтением своей спецификации (читатели должны получить удовольствие от чтения).
Не говорите мне, что у вас от рождения нет дара писать занимательно, я вам не поверю. У всех постоянно возникают смешные мысли, но внутренний цензор ворчит, что это «непрофессионально». Иногда необходимо нарушать правила.
Если вы видели тонны той ерунды, которую я написал для своего вебсайта, то должны были обратить внимание, что я постоянно, то здесь, то там, пытаюсь быть занимательным. Чуть выше я грубо пошутил над чужими мозгами и поиздевался над менеджерами, любящими играть в гольф. Не будучи большим весельчаком, я все же стараюсь шутить, ведь даже попытки писать забавно оживляют текст, как бывает смешон печальный клоун.
В спецификации проще всего быть занимательным, приводя примеры. Рассказывая о том, как работает некая функция, не говорите:
Чтобы создать новую таблицу «Служащие», пользователь нажимает клавиши Ctrl+N и начинает вводить их имена.
Лучше написать примерно так:
Мисс Пигги, тыча в клавиатуру карандашом для подведения глаз, потому что ее маленькие пухлые пальчики слишком толсты, чтобы нажимать клавиши по отдельности, набирает Ctrl+N, чтобы создать таблицу «Бойф-ренды», и вводит в нее единственную запись «Kermit».
Если вы достаточно часто читали Дэйва Барри, то могли обратить внимание, что один из простейших способов быть занимательным — это быть конкретным тогда, когда этого не требуется.
«Мопсы всех мастей» звучит забавнее, чем «собаки». «Мисс Пигги» звучит забавнее, чем «пользователь». Вместо «пользователей с особыми запросами» напишите о «фермерах-левшах, выращивающих авокадо». Не говорите «тех, кто не хочет убирать за своими собаками, следует наказывать»; лучше скажите, что «их следует помещать в такие глухие тюрьмы, где заключенным приходится покупать секс у пауков».
Между прочим, если вы считаете, что быть занимательным — это непрофессионально, то у вас, извините, просто нет чувства юмора. (И не спорьте. Те, у кого нет чувства юмора, всегда это отрицают. Вам меня не провести.)
А если вы работаете в такой компании, где вас будут меньше уважать, если ваши спецификации станут живыми, забавными и приятными для, чтения, то лучше поищите себе другую компанию, потому что жизнь так чертовски коротка, что жаль проводить светлое время суток в таком суровом и несчастном месте.
Правило 2: Спецификация должна напоминать код, предназначенный для выполнения мозгами
Код — текст с приказами компьютеру, что и как делать, программа.
Программистам трудно даются хорошие спецификации, и дело тут, я думаю, вот в чем.
Главной аудиторией написанного кода оказывается компилятор. Да, я знаю, что людям тоже приходится читать код, но обычно им очень трудно это делать.
Большинству программистов достаточно сложно довести код до такого состояния, когда компилятор может прочесть его и правильно интерпретировать; желание сделать код пригодным для чтения человеком оказывается роскошью. Код может быть таким:
void print_count( FILE* a, char * b, int с){
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), определяемая как отображение пользователя х, в RFC-822-совместимый почтовый адрес этого пользователя, представляющий собой ANSI-строку. Предположим далее, что имеются пользователи А и В, причем А должен послать почтовое сообщение пользователю В. Для этого пользователь А инициирует новое сообщение с помощью любого (но не всех сразу) из определенных в соответствующих местах способов и вводит AddressOf (В) в текстовом окне То:.
Но ведь можно было написать иначе:
Мисс Пигги собирается на обед, поэтому она создает новое почтовое сообщение и вводит адрес Кермита в поле «То:».
Примечание: Это должен быть стандартный адрес электронной почты (согласно RFC-822).
Теоретически «смысл» в обоих случаях одинаков, но только первый пример невозможно понять без тщательного дешифрования, а второй пример понять легко. Программисты часто пытаются писать спецификации, похожие на непостижимые научные статьи. Программисты иногда думают, что «корректная» спецификация должна быть «формально» корректной, и уж тут только держись.
Ошибка состоит в том, что при написании спецификации помимо корректности необходима еще и понятность, что на программистском языка означает необходимость написать ее так, чтобы человеческий мозг смол ее «скомпилировать». Одно из существенных различий между компьютером и человеческим мозгом состоит в том, что компьютер может спокойно ждать, пока вы определите термины, которые собрались использовать. Но человек не поймет без предварительных объяснений, о чем вы говорите. Человек не собирается что-то расшифровывать, он хочет читать по порядку и понимать. Человеку надо сначала показать общую картину, а затем уже расписывать детали. Компьютерную программу вы начинаете сверху и двигаетесь вниз, полностью излагая детали. Компьютеру безразлично, имеют ли смысл имена ваших переменных. Человеческий мозг схватывает идею гораздо лучше, если может составить живую картинку по вашему рассказу, даже если это лишь часть рассказа, потому что наш мозг эволюционировал так, чтобы понимать рассказы.
Если опытному шахматному игроку показать позицию, возникшую на доске в середине игры, то он за пару секунд запомнит расположение всех фигур. Но если переставить несколько фигур так, чтобы возникла позиция, которая неосуществима в реальной игре (например, поставить какие-нибудь пешки на первую горизонталь или обоих черных слонов поставить на черные клетки), то запомнить такое расположение фигур на доске шахматисту будет несравнимо труднее.
Компьютеры думают по-другому. Компьютерная программа, которая может запомнить шахматную доску, с одинаковой легкостью запомнит как возможные, так и невозможные позиции. Человеческому мозгу не свойственна работа по принципу прямого доступа; какие-то пути в нашем мозгу оказываются более прочными, и одни вещи проще понять, чем другие, потому что они встречаются чаще.
Поэтому, когда вы пишете спецификацию, постарайтесь представлять себе того, кому она адресована, и что должно быть сделано для него понятным на каждом шаге. С каждой новой фразой старайтесь выяснить, сможет ли читающий понять ее во всей глубине в контексте того, что вы уже ему сообщили. Если кто-либо из ваших предполагаемых читателей может не знать, что такое RFC-822, то вы должны либо дать определение, либо хотя бы упрятать упоминание об RFC-822 в примечание, чтобы какой-нибудь административный работник не прекратил чтение спецификации, столкнувшись с обилием технического жаргона.
Правило 3: Пишите проще
Не пишите неестественным и формальным языком из опасения, что простые предложения выглядят непрофессионально. Язык спецификации должен быть максимально простым.
Часто люди употребляют такие слова, как «утилизировать», потому что просто «использовать» кажется им непрофессиональным. (Опять это слово — непрофессиональный». Будьте уверены, что когда кто-то говорит, что не следует чего-то делать, потому что это «непрофессионально», у него просто нет настоящих аргументов.)
На самом деле, мне кажется, что часто люди, встретив текст, написанный понятным языком, чувствуют в этом какой-то подвох. Разбивайте текст на короткие предложения. Если не удается написать понятное предложение, разбейте его на два или три более коротких.
Избегайте чрезмерно длинного текста — целых страниц, на которых нет ничего, кроме текста. Люди пугаются их и бросают читать. Часто ли вы видели популярный журнал или газету, в которых целая страница была бы заполнена текстом? В журналах иногда даже выхватывают цитату из статьи и печатают ее огромным шрифтом в центре страницы — лишь бы там не представала страница, заполненная исключительно текстом. Вставляйте нумерованные или маркированные списки, рисунки, диаграммы, таблицы и пустые промежутки, чтобы придать странице более легкий вид.
Ничто так не полезно в спецификации, как обилие скриншотов. Одна картинка может быть ценнее тысячи слов.
Правило 4: Исправляйте и перечитывайте текст по нескольку раз
Поначалу я готовился долго рассуждать по поводу этого правила, но оно слишком просто и очевидно. Перечитайте и отредактируйте свою спецификацию несколько раз. Если обнаружите предложение, которое не удается понять с первого раза, переделайте его.
Я сэкономил столько времени, отказавшись от разъяснения правила 4, что могу добавить еще одно правило.
Правило 5: Шаблоны бывают вредны
Не поддавайтесь соблазну сделать стандартный шаблон для спецификаций. Вам может показаться, что хорошо, если «все спецификации выглядят одинаково». Сообщаю: не хорошо. Какой в этом смысл? А книги у вас в доме все выглядят одинаково? А вы бы хотели, чтобы они выглядели одинаково?
Плохо то, что при наличии шаблонов в них часто появляются разделы, которые, как вам кажется, необходимы для каждой функции. Пример: большой Билл заявляет, что отныне в каждый продукт Microsquish будет включена интернет-компонента. Поэтому в шаблоне спецификации теперь есть раздел с названием «Интернет-компонента». Теперь всякий, составляя спецификацию, как бы тривиальна она ни была, должен написать этот раздел «Интернет-компонента», даже если это просто спецификация для клавиатуры. (А вы удивляетесь, почему на клавиатурах, как грибы, стали расти ненужные кнопки для покупок в Интернете).
По мере того как копятся разделы, растет размер шаблона. (Ну кому нужен в спецификации список литературы? Или глоссарий?) Такие большие шаблоны плохи тем, что отбивают желание писать спецификации, и это занятие начинает пугать.
Спецификация — это документ, который хотелось бы, чтобы люди прочли. И в этом он не отличается от рассказа в «Нью-Йоркере» или дипломной работы. Вы когда-нибудь слышали, чтобы профессор раздавал студентам шаблоны дипломных работ? Вы когда-нибудь читали два хороших рассказа, написанных по шаблону? Откажитесь от этой мысли.
Tags: Маркетинг
