5 мифов о документации

Наверное, самая частая жалоба IT-шников – это отсутствие документации на проекте. Желание обрести “peace of mind” и иметь четкую инструкцию, что и за чем надо делать, вполне понятно, однако мифов по поводу документации столь много, что всех сезонов myth busters не хватит на внесение ясности в данный вопрос.

И все же давайте попробуем! Итак, 5 мифов о документации.

Миф1: Чем подробней, тем лучше

Я вам приведу контр-пример. Однажды я имел счастье ознакомиться с архитектурным документом на пару сотен страниц. Я не шучу. Я, наверное, неделю потратил на его изучение. Моя самооценка серьезно упала. Нет, не потому что я "осознал", что до этого жил неправильно и наш дизайн был недостаточно подробен. Я ничего не мог понять в этом документе. На меня вывалились потоки информации, абсолютно не нужные для решения моей задачи. Более того, в итоге выяснилось, что информации конкретно по моей задаче как раз и недостаточно.

То есть детализация имеет мало общего с понятностью и правильностью тезисов.

Поэтому помните – после того, как вы напишите документ, кому-то придется его читать. Причем, если вы напишите его один раз, то читать его будут намного больше раз. Реальная экономия времени как раз в том, чтобы потребители тратили на чтение меньше времени.

Миф2: Навалились, еще чуть-чуть, и вот оно счастье!

Многие думают (точнее не задумывались, просто многим так кажется), что документация это некое разовое усилие. Вот мы сейчас напишем дизайн, согласуем требования, и все будет хорошо на веки вечные. В реальности же, чем подробней вы пишите документацию, тем больше требуется усилий на поддержание её в приемлемом состоянии.

Представьте себе ситуацию, когда документация обновляется, но все время с небольшим опозданием. В итоге, чтобы объяснить какой-то документ другому человеку, все равно документа недостаточно, и нужен кто-то, кто объяснит как оно на самом деле. Доверие к документации падает, после прочтения некого тезиса участники все равно его перепроверяют устно с носителями знаний. На передачу информации тратится столько же времени, как и в случае отсутствия документации. Плюс тратится время на саму документацию. По-моему, мы сами себя обманули?

Миф3: Документации нет. Очевидно, что в этом виноват кто-то другой

Многие думают, что документация должна свалиться на них как манна небесная. На самом деле, по любой методологии разработчики должны принимать участие в документировании всех артефактов, начиная с требований, заканчивая дизайном.

Многим, конечно, невдомек, что это не внешняя, а внутренняя проблема и начинать нужно с себя – например, приучить себя вовремя заполнять журнал (btw, это тоже документация, просто в другом формате). Серьезно, ведь на это нужно всего-то N минут в неделю, если вам так сложно это сделать, то почему вы думаете, что кому-то проще тратить значительно больше времени на другое?

Окей, вы заполняете журнал вовремя. Как на счет комментариев в коде? Каждый ли коммит в репозиторий содержит комментарий? Когда вы закрываете баг, всегда ли вы сопровождаете это комментарием и корректно переводите статусы?

По сути, это тоже документация, просто в другом формате, на чем я бы хотел остановиться поподробней в следующем мифе:

Миф4: Документация – это файлы в формате .doc. Окей, .xls тоже годится

Традиционно результатом code review является .doc файл с табличкой, а может быть и .xls файлик. Удобно ли пользоваться таким документом? В случае если code review проводится группой людей, неплохо бы положить файл в репозиторий. Да, к сожалению, с merge изменений могут быть проблемы – файл лучше блокировать на время редактирования.

Что если список вести как issues в YouTrack, например? Просто пометить их определенным тэгом. Команда может голосовать по каждому пункту, оставлять комментарии и сразу принимать в работу, как любую другую задачу. Лучше, чем .doc, правда?

А что если дизайн вести в wiki? Разработчики могут самостоятельно вносить изменения сразу после того, как поменялась структура кода. Писать, пользуясь разметкой wiki – это по-хакерски, ребятам понравится. Незнакомый термин? Дайте кросс-ссылку, таким образом вы получите не просто текст, но нечто более интерактивное.

Product manager просит вас составить список шагов, который выполняется во время работы CruiseControl. Сделаем ему .xls? А что если аккуратно именовать Ant targets и написать html-страничку, которая красиво показывает, что и за чем следует в Ant скрипте. И поддерживать документ не надо, добавили target – он уже в отчете.

Про банальную генерацию .chm из комментариев в коде даже не буду упоминать.

Миф5: Заказчик постоянно меняет требования. Мы сделаем спецификацию и будем использовать её как щит

Да, пора снять розовые очки – это не работает. Какая основная задача разработчиков? Ну, помимо написания unit-test-ов, нужно, чтобы заказчик был доволен. Если вы упретесь рогом «Погоди, но ведь здесь так написано, даже если тебе это и не нравится», то будет ли заказчик доволен? Наверное, нет, но, скажете вы, по крайней мере, он нам будет обязан заплатить деньги.

Не уверен. Потому что не получится все однозначно описать, наступит праздник и на его улице и недовольный заказчик жестко отыграется на каком-нибудь вашем упущении в спецификации.

А продолжит ли он с вами дальнейшую работу? А посоветует ли он вас своим партнерам? Или все-таки напишет где-нибудь у вас на сайте, что никогда в жизни не будет с вами работать и другим посоветует того же?

В такой ситуации не стоит забывать, что иногда бодаться сложнее (я говорю не про порох в пороховницах, я имею ввиду - затратнее по времени), чем посмотреть, что мы можем сделать и таки обрадовать заказчика.

Итак, самый главный вопрос - «Что делать?»

Документация имеет ряд очевидных минусов, поэтому любой документ должен иметь хорошее обоснование. Некоторые программисты сталкиваются с проблемами при устном общении, надо признать, что писатели из нас тоже посредственные (почитайте мой блог, ну не уныло?), поэтому и писать её никто не хочет.

Тем не менее документация все же пишется и пишется, чтобы решать конкретные проблемы. Если просто удалить все .doc файлы в вашей проектной папке, не придумав взамен другое решение, то вряд ли получится что-то хорошее.

Однако, подумайте об этом с другой стороны. Если продукт хороший и интерфейс интуитивно понятный, часто ли приходиться заглядывать в User Guide? Если у вас огромный Installation Guide, не значит ли это что нужно заняться автоматизацией? В случае подробной спецификации, не работаете ли вы по Waterfall модели – без тесного общения с заказчиком в процессе разработки? Во многих случаях документация – это своеобразный workaround для проблем, которые эффективнее решаются другими способами.

Мартин Фаулер писал в «Рефакторинге», что комментарии внутри метода – это плохой запах часто намекающий на то, что нужен рефакторинг. Если у вас в методе появляется //этот код вычисляет эту штуку вот таким офигенским спосбом, то скорее всего вам нужно выделить кусок кода в метод getШтукаОфигенски(); и комментарий больше будет не нужен.

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

Нужен knowledge sharing? Парное программирование с разработчиками, меняющими пары, поможет распределить опыт и знания внутри команды.

Вместо сложного дизайна и объемных архитектурных документов используется принцип Simple Design (http://www.martinfowler.com/articles/designDead.html), подкреплённый юнит-тестами, непрерывным рефакторингом и code review в результате работы в паре.

Резюмируя, если вам не хочется поддерживать очередной документ, то принюхайтесь, не попахивает ли он неэффективным процессом. Может быть, просто нужно оглянуться назад и внедрить новую инженерную практику, о которой вам рассказывали недавно на тренинге?