敏捷开发，如何编写架构文档
每个系统都包含一系列架构决策，定义了设计和实现的边界和限制，
架构设计文档的核心是以某种方式的选型决策，而开发团队可能不太清楚这个决策背后的假设和思考。
对于这些决策，由于我们缺少当时的上下文，只能盲目的接受和盲目的做出改变。
闲逛ThoughtWorks Radar偶然发现一个在17年和18年都被ADOPT（采用）的技术叫“ADR - Lightweight Architecture Decision Records”，轻量的架构决策记录，针对演进式架构而提出的一种架构文档管理方法。
https://assets.thoughtworks.com/assets/technology-radar-vol-18-cn.pdf
敏捷开发和ADR
敏捷宣言说：“可以工作的软件，强过全面的文档”
(agile manifesto: Working software over comprehensive documentation)
--- 意思不是说不需要文档！
特别是敏捷类型的项目，软件架构需要适应新的业务、市场的变化，架构技术重要的决策是如何做出的，为什么这么选择，背后有怎样的假设。
所以，主要的问题是架构的文档形式和内容，架构文档需要与项目的状态保持紧密的关系，并且简洁，明了，便于维护和阅读，不然，架构的文档就没有人看，更不会有人去更新他。
什么是ADR
接下来我们就来简单看一下什么是ADR，如何解决篇头提出的几个疑虑。
ADR，先来看一下什么是AD（Architecture Decision）？，
在《Documenting Architecture Decisions》一文中说道架构文档应该关注和收集的内容包括：“affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques”。
因此，架构决策，是一个软件设计的选择，涵盖了功能性和非功能性所需要的重要架构选型和设计，系统架构的质量是可以被衡量的（Architecturally Significant Requirement (ASR) ）。
Architectural Decision Record (ADR)是一个单一的架构决策的记录文件，例如架构师所做出的架构决策思考，或者架构设计会要的记录等，而 ADRs 则是维护了一系列架构记录文件集合（ARD），通常存储在项目的 doc/adr 目录下，文件名的格式形如：adr-NNNN-title-with-dashes.md ，或者 NNNN-title-with-dashes.md，NNNN 是一个单调的数字序列，例如 0001.
注意 ，当某个决策被废除，这个旧的ADR文件应该保留，只是做个标记，表示被取代，因为它也是曾经决策思考的结果。
ADR文件的结构：
# [short title of solved problem and solution]
* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] <!-- optional -->
* Deciders: [list everyone involved in the decision] <!-- optional -->
* Date: [YYYY-MM-DD when the decision was last updated] <!-- optional -->
Technical Story: [description | ticket/issue URL] <!-- optional -->
## Context and Problem Statement
[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]
## Decision Drivers <!-- optional -->
* [driver 1, e.g., a force, facing concern, …]
* [driver 2, e.g., a force, facing concern, …]
* … <!-- numbers of drivers can vary -->
## Considered Options
* [option 1]
* [option 2]
* [option 3]
* … <!-- numbers of options can vary -->
## Decision Outcome
Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].
### Positive Consequences <!-- optional -->
* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
* …
### Negative Consequences <!-- optional -->
* [e.g., compromising quality attribute, follow-up decisions required, …]
* …
## Pros and Cons of the Options <!-- optional -->
### [option 1]
[example | description | pointer to more information | …] <!-- optional -->
* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* … <!-- numbers of pros and cons can vary -->
### [option 2]
[example | description | pointer to more information | …] <!-- optional -->
* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* … <!-- numbers of pros and cons can vary -->
### [option 3]
[example | description | pointer to more information | …] <!-- optional -->
* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* … <!-- numbers of pros and cons can vary -->
## Links <!-- optional -->
* [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->
* … <!-- numbers of links can vary -->
注意，有很多项是optional 的，根据情况，自行取舍。
一个例子：（doc/adr/0005-help-comments.md）
5. Help comments
Date: 2016-02-13
Status
Accepted
Amended by 9. Help scripts
Context
The tool will have a help subcommand to provide documentation for users.
It's nice to have usage documentation in the script files themselves, in comments. When reading the code, that's the first place to look for information about how to run a script.
Decision
Write usage documentation in comments in the source file.
Distinguish between documentation comments and normal comments. Documentation comments have two hash characters at the start of the line.
The adr help command can parse comments out from the script using the standard Unix tools grep and cut.
Consequences
No need to maintain help text in a separate file.
Help text can easily be kept up to date as the script is edited.
There's no automated check that the help text is up to date. The tests do not work well as documentation for users, and the help text is not easily cross-checked against the code.
This won't work if any subcommands are not implemented as scripts that use '#' as a comment character.
小结
总结一下，越来越多的基于敏捷的项目开发模式，要求我们有演进式的架构设计眼光，因此我们也需要采用一种类似的技术，去有效的，敏捷的整理架构文档，去跟踪记录你或者你们团队，曾经对一系列功能所做出的架构思考和取舍权衡的过程。
参考
- https://adr.github.io/ Homepage of the ADR
- https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records
- https://www.hascode.com/2018/05/managing-architecture-decision-records-with-adr-tools/ Managing Architecture Decision Records with ADR-Tools
- https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf
- https://agilemanifesto.org
