Меня попросили подготовить обзор существующей ИТ-архитектуры и предоставить документ, содержащий анализ слабых мест и предложения по улучшению каждого из них.
Как сделать этот документ простым для чтения, не перегруженным и в то же время конкретным? Есть ли шаблон, который я могу использовать для такого рода документации?
Кроме того, должен ли я предоставить описание того, как в настоящее время работает конкретный сегмент в системе, прежде чем я объясню, что следует изменить?
Спасибо
Я делал подобные вещи как часть оценки технологий. Обычно он представляет собой оценку , охватывающую как преимущества, так и недостатки, а не только слабые стороны. Я предлагаю получить разъяснения о том, следует ли также учитывать льготы.
Цель такого документа — помочь людям принимать обоснованные решения о технологиях или конструкциях, которые они не полностью понимают. В моем случае лица, принимающие решения, были менеджерами по продукту и бизнесменами, которыми руководили инженеры и другие заинтересованные лица. Ваша аудитория должна понимать проблемы достаточно хорошо, чтобы принимать решения, и ее не волнуют кровавые детали. Они заботятся о последствиях , а не о реализации .
Вы делаете что-то подобное, хотя и менее формально, когда обдумываете крупные покупки. Вы, вероятно, мало знаете о том, как работает ваша печь, но если вы не получаете достаточно тепла, и технический специалист предлагает исправить это, заменив теплообменник, вы хотите достаточно знать о том, что будет означать это изменение. (Возможно, вместо этого вы подумываете о том, чтобы просто купить несколько обогревателей за небольшую часть капитальных затрат.) В вашем случае ваши читатели — такие же люди, как и вы, принимающие решения о системах, о которых они не знают всех деталей. Им нужно достаточно информации, чтобы принять взвешенное решение; они не заботятся обо всех мельчайших подробностях.
Итак, все сказанное, вот типичная структура для таких документов по моему опыту. (Мне не известен конкретный шаблон, который широко используется.)
Общий обзор: страница или меньше о том, где вы сейчас находитесь и какие ключевые факторы необходимо учитывать при оценке. Ключевыми факторами могут быть такие вещи, как безопасность, соответствие стандартам, совместимость и ремонтопригодность. (Если бы вы также оценивали альтернативные решения, это тоже было бы рассмотрено здесь. Кажется, вы не спрашиваете об этом виде оценки, иногда называемом торговым исследованием , поэтому я опущу его из остальной части этого ответа.)
Один раздел на фактор. Для каждого:
Резюме и рекомендации: вы уже дали рекомендации по каждой проблеме; здесь вы собираете их все вместе (на более высоком уровне) для своих читателей. Им нужно прочитать остальные, но когда они встретятся с другими заинтересованными сторонами, чтобы принять решение, они будут работать над этим последним разделом.
Вот набросок примера (без последнего сводного раздела):
Оценка архитектуры Flux Capacitor TM
Наш Flux Capacitor v. 1.0 находится в производстве уже год. Отзывы клиентов и отрасли в целом были положительными, но ключевые клиенты выразили некоторые опасения, и в ходе внутреннего тестирования мы выявили некоторые проблемы, для устранения которых потребуются архитектурные изменения. Эти проблемы включают в себя: (список идет здесь)
- Трудности активации
Flux Capacitor 1.0 активируется при включении управления во время движения со скоростью 88 миль в час. (См. следующий раздел, чтобы узнать об аппаратных зависимостях и доступности Delorean.) Многие наши клиенты, особенно в США, выразили обеспокоенность по поводу юридических и финансовых последствий.
Конструкция Flux Capacitor зависит от настраиваемой частоты квантовой гармоники. Текущее значение 88; другие возможные значения включают 44, 22 и 176. Частоты квантовых гармоник ограничены законами физики, и мы не можем выбрать более удобное значение, такое как 65.
Плюсы:
Скорость 88 миль в час достижима для всех рассматриваемых транспортных платформ. (Сноска: ранее мы отказались от рассмотрения маломощных транспортных средств, таких как Segways.)
Скорость 88 миль в час достаточно высока, чтобы случайное столкновение было маловероятным. У нас было только одно сообщение о такой аварии, которая произошла на автобане.
...
Минусы:
88 миль в час превышает установленный законом предел скорости для большинства наших клиентов. Мы могли бы смягчить это, ускорив окно активации, чтобы сотрудники правоохранительных органов с меньшей вероятностью заметили превышение скорости достаточно быстро, чтобы получить номер лицензии.
У нас возникают трудности с продажей пожилым клиентам, которые предпочитают более умеренные скорости.
...
Рекомендации: Исследуйте использование квантовой гармоники с частотой 44 мили в час и добавление функций безопасности для предотвращения случайного включения. Это позволяет нашим пользователям соблюдать местные законы и достигает рынка пожилых людей. Это изменение по-прежнему позволит устройству соответствовать большинству рассматриваемых в настоящее время платформ; однако он не подходил для Miata. Нам нужно будет разработать и протестировать средства безопасности, чтобы предотвратить негативные последствия поездки по межштатной автомагистрали. Это крупномасштабное изменение требует около 2 миллионов долларов инженерных усилий.
Если вы начинаете с нуля и можете свободно выбирать любую форму, вам следует взглянуть на отличный ответ от Моники Челлио .
Но: если вы работаете в устоявшейся компании, есть большая вероятность, что вам не придется придумывать свои собственные правила форматирования.
Большинство компаний, которые несколько раз проводили подобный процесс, имеют своего рода руководства по стилю или правила написания рекомендации. Есть много вещей, которые, возможно, придется учитывать:
Самое главное при написании рекомендации — спросить своих коллег, знают ли они о таких руководствах по стилю и примерах — потому что ваш текст может быть идеальным, если он не соответствует рекомендациям компании, он не будет хорошо принят.
Выше приведены некоторые моменты, которые вы должны иметь в виду и о которых вы можете спросить. Возможно, вы не можете найти полный документ, но вы нашли управленческие презентации с итоговыми слайдами. Посмотрите, как они устроены, и решите, стоит ли брать их в качестве примера. Например, вы делаете сравнения, просто перечисляя их друг под другом? Или вы ставите Pro слева, а Con справа? Или вы сравниваете два продукта типа «Товар 1 дешевый — Продукт 2 дорогой» со следующей строкой: «Товар 1 предлагает три из четырех запрашиваемых функций — Продукт 2 предлагает четыре из четырех запрашиваемых функций»?
При проведении анализа слабых мест ваша компания предпочитает небольшой обзорный слайд/страницу, за которым следует одна страница для каждого слабого места, а затем переход к «рекомендациям», чтобы обсудить стратегии по смягчению всех слабых сторон вместе? Или ваша компания предпочитает решать проблему в то время и хочет, чтобы вы сразу указали на недостатки, за которыми последовали конкретные «рекомендации» о том, как снизить риск?
Наконец, много "Как бы я это сделал?" зависит от того, сколько времени у вас есть. Если это документация, которая должна документировать то, что вы сделали за последние месяцы, то люди наверняка ожидают, что вы сделаете длинный документ с несколькими короткими абзацами в начале и в конце, которые сообщают руководству, что делать, и с длинными описаниями в середине. это расскажет вашим коллегам, почему вы рекомендовали то, что рекомендовали. Если у вас не так много времени, потому что это, например, не очень важная задача, может быть, просто небольшой проект с еще меньшим бюджетом, тогда вы можете сделать все кратко. Детали зависят от точного контекста, того, что вы можете найти в качестве шаблона в своей компании или получить от своих более опытных коллег и вашей целевой аудитории.
Сецеспит
Александр