Refactor Remote Development Blueprint into Architecture Decision Record format
MR: Pending
Description
Refactor Remote Development Blueprint into Architecture Decision Record format
Acceptance Criteria
TODO: Fill out (required)
-
[Describe what must be achieved to complete this issue.] -
[Describe another requirement needed to complete this issue.] -
[Add additional acceptance criteria as needed.]
Technical Requirements
Discussion from internal slack thread:
grzegorz 10 days ago I haven't read the whole thread here, but wanted to point you to the latest development in writing design docs / blueprints. We adopted ADRs in a way that there is a "Decisions" section that contains immutable ADRs, and the main (very simple) page of the blueprint is always being updated along with the latest ADR. This makes the design doc always up to date, even if the ADRs are becoming outdated (then we indicate that the ADR has been changed on the list). Here is the example: https://gitlab.com/gitlab-org/architecture/gitlab-gcp-integration/design-doc (edited)
grzegorz 10 days ago The main page there probably still needs some updates, but with immutable ADRs it becomes much more manageable.
Chad Woolley 9 days ago
We adopted ADRs in a way that there is a “Decisions” section that contains immutable ADRs, and the main (very simple) page of the blueprint is always being updated along with the latest ADR. This makes the design doc always up to date, even if the ADRs are becoming outdated (then we indicate that the ADR has been changed on the list). Here is the example: https://gitlab.com/gitlab-org/architecture/gitlab-gcp-integration/design-doc
This seems like a great idea. Loose coupling and high cohesion applied to documentation.
@Grzegorz - what would you think of migrating an existing blueprint like the Remote Development blueprint to this approach? How might you go about that?
grzegorz 9 days ago @chad Woolley If I wanted to rewrite the existing Remote Development design doc I would keep the "Vision" section (probably rewriting it a bit to make it more relevant long-term) and would add "Overview" and "Decisions" section. The "Overview" would be a distilled content from "Decisions", describing the current state, updated each time when we add a new ADR. Then I would go back to see what fundamental design decisions have been made, and I would document those to create an immutable register of the decisions. Then I would remove almost everything else (depending on the common sense). Does it answer your question? (edited) :+1::skin-tone-3::+1: 3
Chad Woolley 8 days ago Yes it does, thanks. Cc @vishal Tak
Design Requirements
TODO: Fill out or delete (optional) [If applicable, please provide a link to the design specifications for this feature/enhancement.]
Impact Assessment
TODO: Fill out or delete (optional) [Please describe the impact this feature/enhancement will have on the user experience and/or the product as a whole.]
User Story
TODO: Fill out or delete (optional) [Provide a user story to illustrate the use case for this feature/enhancement. Include examples to help communicate the intended functionality.]