Проектная документация

Проектная документация

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

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

На заметку

Цель разработчика в тестировании на ранней стадии — упростить жизнь других участников проекта, ускорив выполнение работы.

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

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

— Чем раньше внесено предложение, тем больше вероятность, что оно попадет в документ, а потом и в код. Так разработчика в тестировании сможет сильнее повлиять на проект.

— Разработчик в тестировании станет первым человеком, рецензирующим все проектные документы, и не пропустит ни одной итерации. Его знание проекта в целом сможет сравниться только со знанием ведущего инженера.

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

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

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

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

— Согласованность. Убедитесь в том, что текст соответствует диаграммам. Проследите, чтобы документ не противоречил утверждениям, сделанным в других документах.

— Архитектура. Проанализируйте архитектуру, предложенную в документе. Можно ли ее реализовать с доступными ресурсами? Какая инфраструктура будет использоваться? Прочитайте описание этой инфраструктуры и изучите ее подводные камни. Можем ли мы поддерживать предложенную инфраструктуру в нашей системе? Архитектура не слишком сложная? Можно ее упростить? Не слишком ли она проста? Что еще нужно учесть при работе с этой архитектурой?

— Интерфейсы и протоколы. Четко ли в документе определены будущие протоколы? Полностью ли описаны интерфейсы и протоколы, которые будет предоставлять продукт? Соответствуют ли эти интерфейсы и протоколы своим целям? Соответствуют ли они стандартам продуктов Google? Можно ли рекомендовать разработчику пойти дальше и начать писать protobuf-файлы (эту концепцию мы опишем дальше)?

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

На заметку

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

Когда разработчик в тестировании обсуждает результаты рецензирования с автором документации — разработчиком, они оценивают объем работы по тестированию и обсуждают, как распределить эту работу между ролями. Это подходящий момент, чтобы задокументировать, как и зачем разработчикам писать юнит-тесты и какие приемы будет использовать команда, чтобы хорошенько протестировать продукт. Если такая дискуссия конструктивна, значит работа началась успешно.