В этой главе
• Почему документация важна
• Виды документации
• Диаграммы и рисунки как эффективное средство коммуникации
• Стратегии включения документации в текущие процессы
Эта глава не расскажет вам ничего нового: у нас, технарей, все плохо с созданием документации. Редко встретишь компанию, у которой документация в порядке, и чаще всего благие намерения по ее созданию так и остаются лишь намерениями.
Документация похожа на тесты: ее никогда не бывает слишком много. Но сколько ее должно быть? И как узнать, когда ее достаточно?
В этой главе мы выделим области, для которых может хватить и поверхностного описания, а также области, которые должны быть задокументированы во всех подробностях, в том числе те, что имеют решающее значение для бесперебойной работы команды и обеспечения преемственности. Хотя список не будет исчерпывающим, он поможет вам задуматься о том, какую документацию следует создать, чтобы можно было поддерживать работоспособность необходимых для компании систем даже после того, как любой из сотрудников покинет команду.
Документация, если ее регулярно обновлять, не требует особого внимания. Однако, если забросить ее на долгое время, затем придется изрядно попотеть.
Заметки с полей
Один из моих лучших сотрудников
В одной из компаний, где я был техническим директором, возникла необходимость подготовить большой объем документации – как внутренней, так и внешней – для передачи партнерам и обучения. Я нанял опытного технического писателя, имеющего также опыт разработки. Его задача заключалась не в том, чтобы документировать вообще все, а в том, чтобы вести заметки и набрасывать схемы (иногда буквально на салфетке), затем структурировать эти заметки, систематизировать их и приводить схемы к общему формату. Он также определял, когда что-то из этого требовало переработки, и проверял описание каждой новой версии, чтобы понять, какие документы могут нуждаться в обновлении. Прием на работу этого сотрудника оказался одним из моих лучших решений, и я советую всегда иметь технического писателя, если в команде 20 или более инженеров.