Skip to content

feat: Added "internals" MDBook#884

Draft
RobertJacobsonCDC wants to merge 3 commits into
mainfrom
RobertJacobsonCDC_570_internal_docs
Draft

feat: Added "internals" MDBook#884
RobertJacobsonCDC wants to merge 3 commits into
mainfrom
RobertJacobsonCDC_570_internal_docs

Conversation

@RobertJacobsonCDC
Copy link
Copy Markdown
Collaborator

The PR adds an in-repo home for developer-oriented notes and documentation about ixa internals.

  • I moved some content from the GitHub repo wiki and deleted obsolete wiki content.
  • Organized as an MDBook
  • Added a docs:internals mise task but left existing mise run docs behavior the same.

@RobertJacobsonCDC
Copy link
Copy Markdown
Collaborator Author

This is also a natural home for diagrams that aren't (yet) used in the Ixa Book itself.

@RobertJacobsonCDC RobertJacobsonCDC changed the title chore: Added notes on internals feat: Added "internals" MDBook May 9, 2026
@RobertJacobsonCDC RobertJacobsonCDC linked an issue May 9, 2026 that may be closed by this pull request
@RobertJacobsonCDC RobertJacobsonCDC force-pushed the RobertJacobsonCDC_570_internal_docs branch from 65b0397 to 9102459 Compare May 9, 2026 00:26
github-actions Bot added a commit that referenced this pull request May 9, 2026
github-actions Bot added a commit that referenced this pull request May 9, 2026
@github-actions

This comment was marked as off-topic.

Copy link
Copy Markdown
Collaborator

@k88hudson-cfa k88hudson-cfa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@CDCgov CDCgov deleted a comment from github-actions Bot May 12, 2026
@RobertJacobsonCDC
Copy link
Copy Markdown
Collaborator Author

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 idea isn't to be completely comprehensive, only to be useful.
  • These notes shouldn't be an additional development burden. Rather, they should be a way to capture intellectual effort that has already been spent.

@RobertJacobsonCDC RobertJacobsonCDC marked this pull request as draft May 15, 2026 13:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Implementation documentation

3 participants