A place to cache linked articles (think custom and personal wayback machine)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

index.md 7.3KB

4 jaren geleden
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165
  1. title: Documenting Architecture Decisions
  2. url: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
  3. hash_url: 011e34ad5c059996409dc1ee3caa6b17
  4. <h1>Context</h1>
  5. <p>Architecture for agile projects has to be described and defined
  6. differently. Not all decisions will be made at once, nor will all of
  7. them be done when the project begins.</p>
  8. <p>Agile methods are not opposed to documentation, only to valueless
  9. documentation. Documents that assist the team itself can have value,
  10. but only if they are kept up to date. Large documents are never kept
  11. up to date. Small, modular documents have at least a chance at being
  12. updated.</p>
  13. <p>Nobody ever reads large documents, either. Most developers have been
  14. on at least one project where the specification document was larger
  15. (in bytes) than the total source code size. Those documents are too
  16. large to open, read, or update. Bite sized pieces are easier for for
  17. all stakeholders to consume.</p>
  18. <p>One of the hardest things to track during the life of a project is the
  19. motivation behind certain decisions. A new person coming on to a
  20. project may be perplexed, baffled, delighted, or infuriated by some
  21. past decision. Without understanding the rationale or consequences,
  22. this person has only two choices:</p>
  23. <ol>
  24. <li><p><strong>Blindly accept the decision.</strong> </p>
  25. <p>This response may be OK, if the decision is still valid. It may
  26. not be good, however, if the context has changed and the decision
  27. should really be revisited. If the project accumulates too many
  28. decisions accepted without understanding, then the development
  29. team becomes afraid to change anything and the project collapses
  30. under its own weight.</p></li>
  31. <li><p><strong>Blindly change it.</strong></p>
  32. <p>Again, this may be OK if the decision needs to be reversed. On the
  33. other hand, changing the decision without understanding its
  34. motivation or consequences could mean damaging the project's
  35. overall value without realizing it. (E.g., the decision supported
  36. a non-functional requirement that hasn't been tested yet.)</p></li>
  37. </ol>
  38. <p>It's better to avoid either blind acceptance or blind reversal.</p>
  39. <h1>Decision</h1>
  40. <p>We will keep a collection of records for "architecturally significant"
  41. decisions: those that affect the structure, non-functional
  42. characteristics, dependencies, interfaces, or construction techniques.</p>
  43. <p>An architecture decision record is a short text file in a format
  44. similar to an Alexandrian pattern. (Though the decisions themselves
  45. are not necessarily patterns, they share the characteristic balancing
  46. of forces.) Each record describes a set of forces and a single
  47. decision in response to those forces. Note that the decision is the
  48. central piece here, so specific forces may appear in multiple ADRs.</p>
  49. <p>We will keep ADRs in the project repository under doc/arch/adr-NNN.md</p>
  50. <p>We should use a lightweight text formatting language like Markdown or
  51. Textile.</p>
  52. <p>ADRs will be numbered sequentially and monotonically. Numbers will not
  53. be reused.</p>
  54. <p>If a decision is reversed, we will keep the old one around, but mark
  55. it as superseded. (It's still relevant to know that it <em>was</em> the
  56. decision, but is <em>no longer</em> the decision.)</p>
  57. <p>We will use a format with just a few parts, so each document is easy
  58. to digest. The format has just a few parts.</p>
  59. <p><strong>Title</strong> These documents have names that are short noun phrases. For
  60. example, "ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP
  61. for Multitenant Integration"</p>
  62. <p><strong>Context</strong> This section describes the forces at play, including
  63. technological, political, social, and project local. These forces are
  64. probably in tension, and should be called out as such. The language in
  65. this section is value-neutral. It is simply describing facts.</p>
  66. <p><strong>Decision</strong> This section describes our response to these forces. It
  67. is stated in full sentences, with active voice. "We will ..."</p>
  68. <p><strong>Status</strong> A decision may be "proposed" if the project stakeholders
  69. haven't agreed with it yet, or "accepted" once it is agreed. If a
  70. later ADR changes or reverses a decision, it may be marked as
  71. "deprecated" or "superseded" with a reference to its replacement.</p>
  72. <p><strong>Consequences</strong> This section describes the resulting context, after
  73. applying the decision. All consequences should be listed here, not
  74. just the "positive" ones. A particular decision may have positive,
  75. negative, and neutral consequences, but all of them affect the team
  76. and project in the future.</p>
  77. <p>The whole document should be one or two pages long. We will write each
  78. ADR as if it is a conversation with a future developer. This requires
  79. good writing style, with full sentences organized into
  80. paragraphs. Bullets are acceptable only for visual style, not as an
  81. excuse for writing sentence fragments. (Bullets kill people, even
  82. PowerPoint bullets.)</p>
  83. <h1>Status</h1>
  84. <p>Accepted.</p>
  85. <h1>Consequences</h1>
  86. <p>One ADR describes one significant decision for a specific project. It
  87. should be something that has an effect on how the rest of the project
  88. will run.</p>
  89. <p>The consequences of one ADR are very likely to become the context for
  90. subsequent ADRs. This is also similar to Alexander's idea of a pattern
  91. language: the large-scale responses create spaces for the smaller
  92. scale to fit into.</p>
  93. <p>Developers and project stakeholders can see the ADRs, even as the team
  94. composition changes over time.</p>
  95. <p>The motivation behind previous decisions is visible for everyone,
  96. present and future. Nobody is left scratching their heads to
  97. understand, "What were they thinking?" and the time to change old
  98. decisions will be clear from changes in the project's context.</p>
  99. <hr/>
  100. <h1>Experience Report</h1>
  101. <p>You may have noticed that this post is formatted like an ADR
  102. itself. We've been using this format on a few of our projects since
  103. early August. That's not a very long time in the global sense, but
  104. early feedback from both clients and developers has been quite
  105. positive. In that time, we've had six to ten developers rotate through
  106. projects using ADRs. All of them have stated that they appreciate the
  107. degree of context they received by reading them.</p>
  108. <p>ADRs have been especially useful for capturing longer-term
  109. intentions. We have several clients who are stabilizing their current
  110. systems, but looking toward a larger rearchitecture in the
  111. not-too-distant future. By writing these intentions down, we don't
  112. inadvertently make those future changes harder.</p>
  113. <p>One potential objection is that keeping these in version control with
  114. the code makes them less accessible for project managers, client
  115. stakeholders, and others who don't live in version control like the
  116. development team does. In practice, our projects almost all live in
  117. GitHub private repositories, so we can exchange links to the latest
  118. version in master. Since GitHub does markdown processing
  119. automatically, it looks just as friendly as any wiki page would.</p>
  120. <p>So far, ADRs are proving to be a useful tool, so we'll keep using
  121. them.</p>
  122. <h1>More Reading</h1>
  123. <p>Thanks to Philipe Kruchten for discussing the <a href="http://www.computer.org/portal/web/csdl/doi/10.1109/MS.2009.52">importance of
  124. architecture decisions</a>. I'm
  125. told there is more about them in
  126. <a href="http://www.sei.cmu.edu/library/abstracts/books/0321552687.cfm">Documenting Software Architectures</a>
  127. which is near the top of my reading queue.</p>