Одной из первых книг по программированию, которые я взял в руки, была книга Camel. Любой, кто занимался веб-программированием в девяностых, знает, что это была книга О’Рейли Programming Perl. Теперь эти книги пылятся на моей книжной полке.
Я использовал Perl для создания веб-страниц для клиент-серверного приложения базы данных, которое я написал. В моей компании не было никого из знакомых, на которых можно было бы положиться, так что эта книга спасла мою задницу. В конце концов я запустил приложение, оно имело большой успех, и я уехал в Сан-Франциско, чтобы осуществить свою мечту стать интернет-миллионером в формате Dot Com 1.0. Где были документы для замечательного приложения, которое я создал? ¯\_(ツ)_/
Мы любим хорошую документацию, но она страдает одним фатальным недостатком; разработчики ненавидят это писать. Отец психологии программирования, «Джеральд Вайнберг, сказал это лучше всего:
Задача заключается в том, чтобы выделить время для документирования кода. Инженеров оценивают по коду доставки, а не по количеству страниц документации, которую они пишут. Не многие компании нанимают технических писателей для создания надежной документации для внутренних систем. И, честно говоря, когда начинать документировать код, может возникнуть большой вопрос.
Бывают случаи, когда необходима хорошая, четкая и краткая документация. Но в среде, где технологии и процессы быстро меняются, когда над кодом работает несколько разрозненных команд, документация отходит на второй план, даже если это одна из важнейших вещей, которую должна делать команда.
Я часто делюсь с разработчиками идеей создания рабочей документации. Предпосылка проста; много людей работают над кодом, возникают вопросы, и должно быть место, где можно быстро задать эти вопросы и ответить на них. Вы фиксируете эти знания, когда пишете код. На то, чтобы ввести вопрос, уходит не более пары минут, и еще несколько минут на то, чтобы кто-то другой ответил. Затем эти ответы становятся атомарной единицей знаний, которую легко помечать, индексировать и искать.
Это не замена полной документации, особенно документации для конечного пользователя. Однако интерактивная база данных знаний, позволяющая легко спрашивать, отвечать, делиться, искать и записывать, может гарантировать, что не все полезные ноу-хау будут потеряны. Это становится особенно важным для многокомандных проектов, циклов Dojo, Agile-спринтов, инициатив по цифровой трансформации и т. д.
Как выглядит ваш процесс создания внутренней документации? Как определить, что необходимо документировать?
Почему золото золотое?
Вот почему «Голдфингер» до сих пор является моим любимым фильмом о Бонде…
Мы помогаем ИТ-лидерам на предприятиях решать культурные проблемы, связанные с цифровой трансформацией, и переходить к культуре, основанной на сообществе, которая быстрее обеспечивает инновации и ценность для клиентов. Узнайте больше о нашей работе здесь.
