ADR — еще один источник информации для технического писателя
Думаю, многим техническим писателям хотелось бы минимизировать беготню за стейкхолдерами и ожидание от них ответов. В качестве одного из «факторов», который поможет в этом, можно рассмотреть ADR.
ADR (Architecture Decision Record) — это документ, который фиксирует одно важное архитектурное решение, принятое в проекте/продукте, контекст этого решения, рассмотренные альтернативы и последствия. Т.е. ADR создается под конкретное архитектурное решение, а значит, таких документов в компании может быть великое множество.
ADR в разных компаниях может выглядеть по-разному. Но все-таки составители таких документов стараются придерживаться определенной структуры или шаблона. Вот классический шаблон от Майкла Найгарда (автора термина):
1. Title (Заголовок): Лаконичный, с номером (часто последовательным. Примеры: ADR 001, ADR 002).
2. Status (Статус): «Предложен», «Принят», «Устарел», «Отклонен».
3. Context (Контекст): Содержит описание проблемы, требующей решения, технического и бизнес-контекста. Зачастую он отвечает на вопросы «Что заставляет нас принять решение?», «Какие ограничения есть?» и т.д..
4. Decision (Решение): Формулировка и описание самого решения. "Мы будем использовать...", "Мы отказываемся от...". Здесь часто есть подразделы вроде «Детальное описание решения» и «Имплементация», которые можно назвать «самой мякоткой» и источником полезных знаний для техписа.
5. Consequences (Последствия): Что даст это решение? Какие плюсы, минусы, затраты, риски, что нужно изменить? Прямое влияние на команду.
Также в ADR могут описываться процессы тестирования решения (отсюда тоже можно почерпнуть много интересного о том, как все работает), альтернативы (полезная информация для расширения кругозора техписа и погружения в предметную область) и планы на будущее (информация, которая поможет оценить предстоящую нагрузку по документированию).
Технический писатель может/должен не только читать ADR, но и участвовать в их создании
Участие в этом процессе для техписателя может сводиться к следующим функциям:
- Помощь в написании и фасилитации.
- Рецензирование. Техрайтер вполне может быть рецензентом ADR на предмет ясности, полноты, стиля и пр.
- Помощь в управлении жизненным циклом. ADR могут устаревать, заменяться. Техпис может принимать участие в отслеживании статусов и актуальности информации в ADR.
Получается, если в вашей компании принято писать ADR, вас можно поздравить. Ведь в вашем распоряжении есть кладезь полезной информации, которая точно пригодится при документировании продуктов, процессов и прочих вещей. А если ADR у вас писать не принято, есть смысл попробовать предложить внедрить практику их создания: этим вы сможете нанести пользу немалому количеству людей.
Думаю, многим техническим писателям хотелось бы минимизировать беготню за стейкхолдерами и ожидание от них ответов. В качестве одного из «факторов», который поможет в этом, можно рассмотреть ADR.
ADR (Architecture Decision Record) — это документ, который фиксирует одно важное архитектурное решение, принятое в проекте/продукте, контекст этого решения, рассмотренные альтернативы и последствия. Т.е. ADR создается под конкретное архитектурное решение, а значит, таких документов в компании может быть великое множество.
ADR в разных компаниях может выглядеть по-разному. Но все-таки составители таких документов стараются придерживаться определенной структуры или шаблона. Вот классический шаблон от Майкла Найгарда (автора термина):
1. Title (Заголовок): Лаконичный, с номером (часто последовательным. Примеры: ADR 001, ADR 002).
2. Status (Статус): «Предложен», «Принят», «Устарел», «Отклонен».
3. Context (Контекст): Содержит описание проблемы, требующей решения, технического и бизнес-контекста. Зачастую он отвечает на вопросы «Что заставляет нас принять решение?», «Какие ограничения есть?» и т.д..
4. Decision (Решение): Формулировка и описание самого решения. "Мы будем использовать...", "Мы отказываемся от...". Здесь часто есть подразделы вроде «Детальное описание решения» и «Имплементация», которые можно назвать «самой мякоткой» и источником полезных знаний для техписа.
5. Consequences (Последствия): Что даст это решение? Какие плюсы, минусы, затраты, риски, что нужно изменить? Прямое влияние на команду.
Также в ADR могут описываться процессы тестирования решения (отсюда тоже можно почерпнуть много интересного о том, как все работает), альтернативы (полезная информация для расширения кругозора техписа и погружения в предметную область) и планы на будущее (информация, которая поможет оценить предстоящую нагрузку по документированию).
Технический писатель может/должен не только читать ADR, но и участвовать в их создании
Участие в этом процессе для техписателя может сводиться к следующим функциям:
- Помощь в написании и фасилитации.
- Рецензирование. Техрайтер вполне может быть рецензентом ADR на предмет ясности, полноты, стиля и пр.
- Помощь в управлении жизненным циклом. ADR могут устаревать, заменяться. Техпис может принимать участие в отслеживании статусов и актуальности информации в ADR.
Получается, если в вашей компании принято писать ADR, вас можно поздравить. Ведь в вашем распоряжении есть кладезь полезной информации, которая точно пригодится при документировании продуктов, процессов и прочих вещей. А если ADR у вас писать не принято, есть смысл попробовать предложить внедрить практику их создания: этим вы сможете нанести пользу немалому количеству людей.