Когда мы играли в КВН, одна шутка могла занять весь вечер. Слова переставлялись до тех пор, пока фраза не начинала звучать так, как задумывалась. К этому моменту она уже выучивала дорогу домой и начинала требовать гонорар.
С документацией всё похоже, только после шутки человек должен рассмеяться, а после инструкции — понять, что делать. Причём именно так, как понял автор.
Однажды, когда мы приучали коллег ставить задачи письменно, а не передавать их устно, как какое-то тайное знание, мне пришёл документ на четырнадцать страниц. Он выглядел внушительно. До самой задачи, впрочем, ещё нужно было добраться.
Я спросил: отвечать по пунктам или по существу? Выбрали второе. Мой ответ занял пару страниц, а по ходу разговора оказалось, что сначала нужно уточнить требования. В итоге большую часть нужного сделали с помощью пары готовых плагинов.
Четырнадцать страниц не делали задачу сложнее — просто прятали её.
Я не против подробностей: иногда без них никак. Но у каждой строки должна быть работа. Объём сам по себе не гарантирует точности, а серьёзный вид документа — не залог того, что внутри есть ясность.
Для меня хорошая документация — это не священный пергамент, а текст, который я прочитал, понял, что делать, и не вынужден угадывать пропущенные решения. И я могу рассчитывать, что другие читатели поймут то же самое.
Упаковать такой смысл на одну страницу порой сложнее, чем заполнить четырнадцать. Но читателю, к счастью, не обязательно знать, сколько часов ты гонял эту фразу по столу.