feat: Added "internals" MDBook#884
Conversation
|
This is also a natural home for diagrams that aren't (yet) used in the Ixa Book itself. |
65b0397 to
9102459
Compare
This comment was marked as off-topic.
This comment was marked as off-topic.
k88hudson-cfa
left a comment
There was a problem hiding this comment.
Generally speaking, I think this kind of design documentation is difficult to keep up to date as code evolves but is useful to understand the original intent of the authors if somebody wants to go back in history and figure out why things were implemented a certain way. I'd recommend treating some of this as a series of snapshots (like an Architectural Decision Record or similar), which we could make a section for.
If you intend to keep this up to date, it's not particularly well-suited to being maintained in a collaborative way: breaking it up into sections and having it live closer to the code would be an improvement IMO.
|
Based on discussion, I'm going to rework this to have a more "Architectural Decision Record" (ADR) structure. Example: https://github.com/mozilla/fxa/blob/main/docs/adr/0028-evaluate-playwright.md. The idea is, architectural descriptions are presented in a more "snapshot" format than as a living document that needs to be kept in sync. This also gives me a natural place for some of the more detailed notes I have historically been shoving in a PR description. Some editorial thoughts.
|
The PR adds an in-repo home for developer-oriented notes and documentation about
ixainternals.docs:internalsmise task but left existingmise run docsbehavior the same.