Restructure

.github/dependabot.yml

@@ -1,14 +1,21 @@
 version: 2
 updates:
-- package-ecosystem: npm
-  directory: "/"
-  schedule:
-    interval: daily
-    time: '20:00'
-  open-pull-requests-limit: 10
-- package-ecosystem: bundler
-  directory: "/"
-  schedule:
-    interval: daily
-    time: '20:00'
-  open-pull-requests-limit: 10
+  # The bundler ecosystem was dropped with the Hugo site; there is no Gemfile.
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      # astro and its integrations have to move together.
+      astro:
+        patterns:
+          - "astro"
+          - "@astrojs/*"
+
+  # Workflow actions are pinned by SHA, so without this they never get updates.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

.github/workflows/gh-pages.yml

@@ -11,6 +11,8 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 0 # lastUpdated reads commit dates
 
       - name: Setup Node
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0

CONTRIBUTING.md

@@ -1,28 +1,60 @@
-# How to Contribute
+# Contributing
 
-We'd love to accept your patches and contributions to this project. There are
-just a few small guidelines you need to follow.
+This repository holds the documentation for [UQ XNAT](https://docs.xnat.rcc.uq.edu.au),
+operated by the Research Computing Centre at The University of Queensland.
 
-## Contributor License Agreement
+Corrections are welcome from anyone who uses the service. If a screenshot is out
+of date or a step no longer matches what XNAT does, that is worth reporting even
+if you do not fix it yourself.
 
-Contributions to this project must be accompanied by a Contributor License
-Agreement. You (or your employer) retain the copyright to your contribution;
-this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to <https://cla.developers.google.com/> to see
-your current agreements on file or to sign a new one.
+## Quickest way to fix a page
 
-You generally only need to submit a CLA once, so if you've already submitted one
-(even if it was for a different project), you probably don't need to do it
-again.
+Every page has an **Edit page** link at the bottom. It opens the file in the
+GitHub web editor, where you can make a change and open a pull request without
+cloning anything.
 
-## Code reviews
+## Working locally
 
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
+```sh
+npm install
+npm run dev      # http://localhost:4321
+npm run build    # production build, run this before opening a PR
+```
 
-## Community Guidelines
+Content lives in `src/content/docs/`, one directory per section. Screenshots sit
+beside the page that uses them. The sidebar and the URL redirects are both in
+`astro.config.mjs`.
 
-This project follows
-[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
+## Writing conventions
+
+- **Australian English** — anonymise, organisation, de-identified.
+- **Second person, imperative.** "Select **Upload**", not "we can select Upload".
+- **Every page needs `title` and `description` frontmatter.** The description is
+  the meta description, the social card text and the search result snippet, so
+  make it a real sentence rather than a repeat of the title.
+- **Sentence case for headings**, and at least two `##` headings per page so the
+  table of contents has something to show. Do not open a page at `###`.
+- **Quote the interface exactly.** If XNAT's button says **Begin Upload**, write
+  that, in bold, with the same capitalisation.
+- Prefer `<Steps>` for ordered procedures, `<Tabs>` for mutually exclusive
+  paths, and plain prose for explanation.
+
+## Screenshots
+
+- **Never include real patient data, or anything that could identify a
+  participant.** Use a demo project with synthetic data. This is a public
+  repository and its history cannot be quietly rewritten.
+- Colocate images with the page that references them.
+- Write alt text describing what to look for, not what the page is.
+
+## Renaming and moving pages
+
+A page's URL comes from its filename, so renaming a file changes its URL. The
+site carries around 60 redirects for URLs that already exist in the wild
+(`astro.config.mjs`). If you move or rename a page, add a redirect from the old
+path and check the build still passes.
+
+## Review
+
+Pull requests are reviewed by RCC. For anything about the service itself rather
+than the documentation, contact `rcc-support@uq.edu.au`.

REVIEW.md

@@ -0,0 +1,73 @@
+# Docs review queue
+
+Questions that can't be answered from the codebase, the screenshots or public
+XNAT documentation. Grouped by what they block.
+
+## Blocks launch
+
+- [ ] **De-identification obligations.** Who is responsible for de-identifying
+      before upload? What ethics approval is presupposed? What must a user do if
+      identifiable data reaches the archive, and will RCC purge it?
+      Currently the only statement of this anywhere is a `:::note` inside step 1
+      of `uploading-data/web-upload.mdx`.
+- [ ] **Site anonymiser coverage.** `anonymising-data/site-anonymiser.md` says
+      HIRF and CAI data is anonymised on-site. `getting-started` names HIRF, CAI
+      **and TRI**. Which is right, and is the DICOM tag table current? This is a
+      privacy claim, so it needs to be exact.
+
+## Blocks new pages
+
+- [ ] **Data residency and lifecycle.** Where do the bytes actually live? Does
+      deleting in XNAT delete in UQ-RDM? What happens at project end? Backups?
+- [x] **Who can create a project.** Answered: UQ users can request their own.
+      Non-UQ AAF users and non-AAF users cannot; their projects are created by
+      the facility or they are granted access by a project lead. Non-AAF users
+      additionally need an AAF VHO account first. Captured in
+      `using-xnat/projects/your-project.mdx`.
+- [ ] **Facility project creation.** Projects for HIRF, CAI and TRI data are
+      sometimes created automatically and sometimes not. What determines it?
+      The Facility data tab currently tells users to check their project list
+      and contact the facility if it is missing, which avoids the question but
+      does not answer it.
+- [ ] **Automated facility uploads.** With CTP retired, what sends imaging data
+      from HIRF, CAI and TRI scanners to XNAT, and who operates it? How long
+      does it normally take, does the data land in the project directly or wait
+      in the prearchive, and how long should a user wait before chasing it —
+      with the facility or with RCC support? Blocks
+      `uploading-data/facility-uploads.md`, currently `draft: true`.
+- [ ] **Which instance for which user.** `xnat.rcc` vs `opex.xnat` vs
+      `irc5.xnat`. The homepage flags the latter two as UQ network or VPN only,
+      and `partials/sign-in-aaf.mdx` already hedges with "if you have been
+      provided with a project specific XNAT link, use that one instead" —
+      that hedge exists because the rule was never written down.
+- [ ] **Support routing.** When is it `rcc-support@uq.edu.au` vs
+      `HIRFAdministration@health.qld.gov.au`? Business hours? Escalation path?
+      The "~24 hours" turnaround appears on two pages with no source.
+
+## Corrections to existing pages
+
+- [ ] **XNAT version in production.** Determines whether the quoted UI strings
+      are right.
+- [ ] **"Simply downloaded archive structure"** — quoted on the downloading page.
+      Is the real checkbox label "Simplify downloaded archive structure"? Left
+      verbatim rather than silently corrected.
+- [ ] **Alias token expiry.** `alias-tokens.md` says 60 days. This is
+      site-configurable in XNAT — confirm for this instance.
+- [ ] **Storage quota.** "1TB storage and 1 million files" — current? Per
+      project or per user? What does a user see when they hit it?
+- [ ] **Feature availability.** The Actions menu in `using-xnat/subjects.png`
+      shows XSync, Pipelines and Event Service. None are documented. Are they
+      generally available, restricted, or disabled?
+- [ ] **AAF Keycloak login error.** There is an unused screenshot at
+      `logging-into-xnat/ais-keycloak-login-error.png` showing "Unexpected error
+      when authenticating with identity provider". What is the fix? Someone hit
+      this and never wrote it up.
+- [ ] **FAQ content.** `user-guides/faq.md` is an honest placeholder. Real
+      questions from the ticket queue would be better than invented ones.
+
+## Drafted content awaiting sign-off
+
+Pages drafted from screenshots and public XNAT docs are marked either
+`draft: true` (excluded from production builds) or with a review banner and a
+sidebar badge. Nothing drafted should be published without a pass from someone
+who runs the service.