Skip to content

Move MIR docs out of staging#37

Merged
s-makin merged 7 commits intoubuntu:mainfrom
s-makin:mir-improvements
Jun 3, 2025
Merged

Move MIR docs out of staging#37
s-makin merged 7 commits intoubuntu:mainfrom
s-makin:mir-improvements

Conversation

@s-makin
Copy link
Copy Markdown
Collaborator

@s-makin s-makin commented Jun 3, 2025

This PR moves the MIR docs from being displayed in the staging area to being part of the actual docs. I have not added contextual text to most of the landing pages, as the pages themselves may be moved, but I have included a sample of the sort of thing we could have on the how-to/archive-admin/index page.

Some things to note:

  • All MIR pages are in docs/MIR/ to simplify the ACL setup. Any page added to this folder will be subject to the ACL check, rather than setting the controls on individual pages.
  • I have added the "mir" prefix to every MIR-related page except the grand overview, so that if any other sections have similar headings, they remain unique.
  • We need to test if moving pages between Diataxis sections will also trigger the ACL check.

The next step is to actually set up the ACLS -- then I will do the wording changes discussed with cpaelzer so that the MIR team can review them.

@s-makin s-makin requested a review from rkratky as a code owner June 3, 2025 08:51
@rkratky
Copy link
Copy Markdown
Collaborator

rkratky commented Jun 3, 2025

I have added the "mir" prefix to every MIR-related page except the grand overview, so that if any other sections have similar headings, they remain unique.

Thinking out loud: would it make sense to establish a rule to have a topic/area prefix for everything? The possibility of similar headings seems high across the board.

We need to test if moving pages between Diataxis sections will also trigger the ACL check.

By this, you mean, for example, removing a MIR item from one index.md and adding it to another? If yes, then no -- the check would only be triggered if the actual bits (the MIR file) change. It's on Git level, and Git doesn't care (doesn't know) what happens with the files when Sphinx builds the docs.

Copy link
Copy Markdown
Collaborator

@rkratky rkratky left a comment

Choose a reason for hiding this comment

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

A couple of nits. Pre-approved.

@s-makin
Copy link
Copy Markdown
Collaborator Author

s-makin commented Jun 3, 2025

Thinking out loud: would it make sense to establish a rule to have a topic/area prefix for everything? The possibility of similar headings seems high across the board.

The more I've been looking at the wiki content, the more I think that seems like a sensible approach. Many of the headings within pages are repetitive, and if we're splitting pages apart then chances are we'll run across duplicates that have to be disambiguated.

By this, you mean, for example, removing a MIR item from one index.md and adding it to another?

That is what I meant - thanks for clarifying my expectations :)

@s-makin s-makin merged commit e4341c2 into ubuntu:main Jun 3, 2025
2 of 3 checks passed
@s-makin s-makin deleted the mir-improvements branch July 3, 2025 14:29
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.

2 participants