Page History

...

1. RRDMWG - a discussion arose about specific practices that might or might not be adopted re: managing the schemas of the database. 
2. It was requested that we document said  architectural decisions in some consistent way
3. Today's discussion concerns how said decisions are recorded. One example: HL Fabric. How was it chosen? What role is it filling? This question has arisen many times - we need to be prepared and resourced (resourceful) when it is asked. This will also ensure a consistency of response.
4. The first step: deciding how architectural decisions are captured (a meta decision about making decisions)
5. Options to be explored today and consensus sought.
6. Decisions to be made
   1. How do we capture decisions? Where do we keep them? And how do we govern them? 
      1. Common thinking in the past: if decisions are not so controversial they need less consensus. 
      2. However, more controversial decisions need clarity on what, who was part of the decision, how was it reached? 
      3. Options for where to put it? (e.g., Github)
      4. The governance of it (How do we manage the acceptance of an architecture decision as part of our architecture?)
      5. Suggestion: JB - as a test case, the group could start with something like the decision to use MongoDB ahead of PostgreSQL. 
      6. KS: would prefer to start out with the documentation method before diving into the tech decisions themselves - i.e., the basic process of doing it with the tool and the discussion points.
      7. Request to group for options - suggestion from Ken wrt adrgithub.io ('ADR' - Architectural Design Records) - a process that captures architecture decisions, maintains them in a repository. Can only become difficult if there is more than one repository for a given project. Also a potential issue that non-developers aren't necessarily all familiar with Github.
      8. To Ken the most valuable aspect and the most pertinent to openIDL's needs is the template provided at https://adr.github.io/madr/ (Markdown Any Decision Records) - a template for captring architectural decisions in markdown. Lightweight format, documentation for it, a template that is available. Basically laid out as a main page (in wiki). In confluence, you can click on the decisions individually to se what they are. Contents of MADR are fairly straightforward - goes through the following:
         1. status
         2. date
         3. deciders
         4. consulted
         5. informed
      9. Suggestion arose that a repository might be advantageously created that is specifically for documentation apart from the other repositories.
      10. Documents must be easy to manage - so a light markdown based implementation is preferable - editing without downloading (possible in Github) - leaving a record in the repository.
      11. Questions to group about other options (other than ADR/MADR) they would consider. 
          1. Faheem: ADRs are great, but it also depends on the degree the documentation is done - (how granular?) - possible to lose the picture if you do too many ADRs
          2. Faheem:@ hanover - two templates: a technology selection template (opposing forces, requirements, options, costs - similar to adr - then you make a recommendation). Similar to adr but at a higher level. They also use standard documentation templates, diagram-heavy, etc., to walk through architecture.
      12. It was stressed that consequential/pivotal architectural decisions are the ones that most need to be documented
      13. Ken asked Faheem if it would be possible to share the Hanover's templates, and Faheem agreed to look into this.
      14. Goal  in working with ADR: end with dozens of these not hundreds.
      15. No additional templates or processes suggested.
      16. Ken suggested that we start with ADR perhaps supplemented with additional fields, and then start trying to flesh out secondary and tertiary areas of the form, such as 'Technology Selection Template' and 'Document Template.'
   2. Wrt decision of where to put records - will go into wiki for now, perhaps can be put into github later.

...