Определение правильного количества документации

Где я сейчас работаю, общий подход -

по возможности избегайте документации

Только документ, если это понадобится другой команде

просто для пояснения, я не имею в виду документацию по коду - это мы имеем в виду, я имею в виду всю документацию, окружающую процесс проектирования - если это схемы UML или DB, диаграммы классов и текстовые документы со спецификациями и тому подобное.

Я перечислю причину моего босса, чтобы не документировать:

1. это отнимает много времени - сосредоточиться на реализации
2. если дизайн изменится - тогда документация должна измениться, двойная проблема
3. в конце вы просто получаете сотни страниц, которые никто не хочет читать, и никто не редактирует их, так что со временем они устаревают
4. Это боль - никто не хочет этого делать

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

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

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

мой вопрос:

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

Я обнаружил, что ЛЮБАЯ документация лучше, чем НЕТ документации. Соответствующая сумма обычно определяется количеством времени, которое мы должны сделать, или тем, насколько мы ненавидим телефонные звонки и электронные письма поддержки.

Похоже, что ваши нынешние члены команды имеют некоторые нереалистичные ожидания своих воспоминаний, или они стыдятся своих навыков письма и не хотят практиковать.

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

Лучший способ приблизиться к документации - написать ее КАК ВАМ, точно так же, как писать тестовый код. Удивительно, как несколько предварительно написанных шаблонов (с заголовками, заглушками кода и т. Д.) Могут сделать документацию проще и быстрее. Таким образом, вы можете зафиксировать изменения, как они происходят, и у вас будет меньше возможностей для покрытия с течением времени. Таким образом, вы более эффективны, так как можете обращаться к документации по мере необходимости и вносить в нее изменения. Например, выполнение вики облегчает обновления, и вы можете избежать проблем с версией документа, если последние и лучшие версии всегда находятся в сети в одном и том же месте, и вы можете просто отправлять ссылки людям, которым необходимо их прочитать.

Если вы потратите немного времени на документирование, вы ВСЕ будете работать быстрее, особенно когда кто-то новый присоединится к команде, так как им не придется тратить все это время на выяснение всего. Выяснение вещей - это интересная часть нашей работы, но это не весело, когда нужно делать это в спешке, чтобы наладить производство. Мы бы сэкономили много времени, если бы написали еще пару заметок.

У вашей команды такие же проблемы с тестированием или написанием тестового кода? Если нет, это будет легче продать.

Ваша документация полезна во многих отношениях:
1) Для вас, прямо сейчас, и для ваших коллег, когда вы работаете над проектом.

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

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

4) Для вас и других, если ситуация становится политической или спорным. Как человек, который делает записи на собраниях, чтобы не засыпать и бороться со скукой, я часто был единственным с письменной версией решения. Человек, который записал это, выигрывает спор. Вспомните это в следующий раз, когда кто-то скажет: «Помните ту встречу, которую мы провели прошлой зимой в конференц-зале 4, когда мы обсуждали Х? Фред был там, и кто этот парень из Бухгалтерии?»

У моих последних нескольких работодателей у нас была вики "разработки". Значительные фрагменты функциональности (новый фид импорта / экспорта, как работает подсистема безопасности, где система хранит загруженные документы и т. Д.) - все это документируется там. Обычно это обязательный элемент, который необходимо заполнить до шага проверки кода. Обычно вначале это немного сопротивляется, но как только кому-то нужно пойти посмотреть на информацию, и она там, у вас есть другой новообращенный.

Хорошая вещь в его вики-формате заключается в том, что вы гораздо менее склонны делать все красивое форматирование Word и тому подобное и просто записывать реальную информацию, которую вам нужно сохранить. Большинство (если не все) вики-пакетов позволяют загружать документы или изображения (например, диаграммы Visio UML или каркасы пользовательского интерфейса), поэтому вы также можете иметь визуальные элементы.

Как и большинство вещей, я думаю, вы должны стремиться сделать минимальную сумму, которая могла бы работать. Это не то же самое, что никто, хотя.

Вы не можете избежать выделения времени, чтобы написать надлежащую документацию. Сбалансируйте, сколько хотите, в зависимости от того, сколько работы вам дано, но оставьте хорошие 15-20% своего времени, чтобы задокументировать, что вы сделали. Все в команде должны быть на борту, включая вашего менеджера, иначе вы будете только документировать в интересах других и ничего не получите взамен. Документирование должно быть неотъемлемой частью вашего процесса разработки.

Документация должна сообщить вам, ПОЧЕМУ вы что-то сделали, оставляя часть HOW для реального кода, а часть WHAT для модульных тестов. Все остальное - боль. Это обычно достаточно для умных людей, которые просто хотят отправной точкой.

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

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

Ваш начальник прав, не печатайте документацию UML, которую никто не будет читать. Что мы делаем в нашей команде, так это перемещаемся по модели в реальном времени, используя представления диаграмм классов. Принцип состоит в том, чтобы всегда обновлять MOF, модель UML в прямом эфире из кода, и позволить диаграмме классов быть только средством просмотра модели, но не самой моделью.

Это работает очень хорошо, потому что вся сложность выполняется в бэк-офисе на уровне модели. Я могу реорганизовать свой проект, написать документ Java или написать документацию UML в модели. Это своего рода щелчок и вперед. При нажатии вы получаете живую документацию. Если что-то не понятно, тогда я открываю диаграмму классов и начинаю играть с ней. Удалить из классификаторов диаграмм, добавить новые классификаторы, увеличить и уменьшить масштаб, показать связь, удалить связь и т. Д. Модель не изменяется, потому что я не создаю новую информацию о модели, я просто использую ее.

Действительно важно открыть диаграмму пакета и иметь возможность читать непосредственно на диаграмме классов комментарий о том, каким должен быть этот класс. Что должен делать этот метод и каков поток и т.д ....

UML великолепен, действительно полезен, но мы должны прекратить использовать Devleopment, управляемый моделями, чтобы обеспечить большую гибкость и большую итерацию на этапах моделирования / разработки. Диаграмма классов обновляется в реальном времени из кода, а документация всегда точна и доступна одним щелчком мыши. Я не буду упоминать инструмент, но если вы используете Java и Eclipse, легко найти, какой инструмент я использую :-)