Книга: Пользовательские истории. Искусство гибкой разработки ПО
Назад: Перестаньте пытаться написать идеальную документацию
Дальше: Документируйте, чтобы активизировать воспоминания

Хорошие документы похожи на фотографии из отпуска

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

 

 

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