Ni boyinsha

Варианты применения архитектурной документации
Характер архитектуры любой системы обусловливается предъявляемыми к ней требованиями; это утверждение справедливо и по отношению к документации архитектуры — другими словами, содержание документации зависит от предполагаемых вариантов ее применения. Документация ни при каких обстоятельствах не может быть универсальной. С одной стороны, она должна быть абстрактной и, следовательно, доступной для понимания новыми сотрудниками, но с другой — весьма детальной — настолько, чтобы ее можно быть использовать как план про-ведения анализа. Между архитектурной документацией, предназначенной, скажем, для проведения анализа безопасности, и архитектурной документацией для изучения конструкторами должны существовать серьезные различия. С другой стороны, у этих вариантов будет мало общего с содержанием руководства для ознакомления, предназначенного новому сотруднику.
Архитектурная документация одновременно инструктивно и описательна. Ограничивая диапазон возможных решений, с одной стороны, и перечисляя принятые ранее проектные решения по системе — с другой, она обязывает соблюдать определенные принципы.
Из всего этого следует, что заинтересованные в составлении документации лица преследуют разные цели — от представленной в ней информации они требуют разной направленности, разных уровней детализации и разных трактовок. Предполагать, что один и тот же архитектурный документ будет одинаково воспринят всеми без исключения заказчиками, наивно. Стремиться следует к тому, чтобы любое заинтересованное лицо смогло быстро найти необходимую информацию, как можно меньше в процессе ее поиска натыкаясь на незначительные (с его точки зрения) сведения.
В некоторых случаях простейшим решением представляется создание нескольких документов, предназначенных для разных заинтересованных лиц. Впрочем, как правило, задача ограничивается созданием единого комплекта документации с дополнительными облегчающими поиск сведений инструкциями.
Согласно одному из фундаментальных правил технической документации в общем и документации программной архитектуры в частности, составитель должен принимать позицию читателя. Без труда составленная, но трудная для восприятия (с точки зрения читателя — в данном случае заинтересованного лица) документация не найдет себе применения.
Для того чтобы понять, как структурировать документацию и повысить удобство ее использования, следует составить представление о заинтересованных лицах и разобраться в том, для чего она им может понадобиться.
Среди заинтересованных лиц встречаются как умудренные опытом люди, так и новички. Информация, которая им нужна, отличается не по содержанию, а по детализации — новичку она потребуется в «облегченном» виде. Архитектурная документация должна успешно вводить в курс дела всех, у кого есть такая потребность: новых разработчиков, инвесторов, временных участников проекта и т. д.
Одним из самых пристрастных потребителей архитектурной документации по прошествии некоторого времени становится сам архитектор — либо непосредственный проектировщик документированной архитектуры, либо его преемник. В обоих случаях это человек, проявляющий к рассматриваемой архитектуре недюжинный интерес. Новые архитекторы, естественно, стремятся узнать, как их предшественники справлялись с теми или иными задачами и почему они принимали определенные решения.