QUA-1756: Restructure anomaly docs and document Assignees#1121
Open
RafaelOsiro wants to merge 12 commits into
Open
QUA-1756: Restructure anomaly docs and document Assignees#1121RafaelOsiro wants to merge 12 commits into
RafaelOsiro wants to merge 12 commits into
Conversation
RafaelOsiro
requested review from
Hitsu-360,
ets,
gasscoelho,
josecsotomorales,
pelegolas9 and
shindiogawa
3 tasks
- Remove em-dashes across anomaly docs (status, source-record, insights,
detection, overview, fingerprints).
- Fix tag-edit permission in edit-tags how-to: Editor -> Author, aligning
with the backend (PUT /api/anomalies/{id} requires Author baseline;
only description additionally requires Editor).
- Add cross-link hub pointer in edit-description so legacy edit-anomalies
arrivals find edit-tags and add-assignee.
- Flatten redundant ../deep-dive/assignees.md self-reference in insights.
- Add 6 missing legacy redirects (anomalies-in-datastore, anomaly-details,
manage-anomalies, overview-of-an-anomaly, universal-anomaly,
what-is-anomaly) so external links keep resolving.
RafaelOsiro
force-pushed
the
qua-1756-anomaly-assignees
branch
from
e423a82 to
27da3a6
Compare
- Normalize team permission terminology ("<level> team permission")
across Deep Dive assignees, add/remove/bulk how-tos, API, and FAQ.
- Fix factually wrong hard-delete constraint in API: hard-delete
works on any anomaly, not just archived (validated against
controlplane).
- Refine Deep Dive assignee descriptions: avatar/name display rules,
inheritance from check defaults, notification triggers (status,
tags, description, assignees), and Author requirement on
self-assignment.
- Drop redundant H2s and "picker component" leak in add/remove/bulk
how-tos; replace with "user picker" wording.
- Standardize tab labels to "From Explore > Anomalies" and "From the
Anomaly Overview" in how-tos.
- Treat the close icon in the user picker as an icon (not a button)
in remove-assignee how-to.
- Split anomalies/how-tos/edit-tags.md into three sibling pages under
anomalies/how-tos/tags/: add-tags.md (Overview/Explore tabs),
remove-tags.md (Overview/Explore tabs, screenshots TBD), and
bulk-edit.md (Datastore/Check Template tabs).
- Mirror the Assignee how-to architecture: same tabs, same step pattern,
parallel naming ("Tags field", clean +/Edit icon phrasing).
- Add mkdocs.yml nav entry "Tags" replacing the flat "Edit Tags", and
redirect anomalies/how-tos/edit-tags.md to tags/add-tags.md.
- Create docs/assets/anomalies/how-tos/shared/ for the first 6 steps of
the bulk flow (anomalies list to modal opens), reused by both
bulk-assign.md and bulk-edit.md.
- Move bulk-assign steps 1-6 (datastore + check-template) into shared/;
keep steps 7-11 inside assignee/bulk-assign/.
- Place bulk-edit-specific assets (datastore + check-template steps
7-11) inside tags/bulk-edit/ following the standard
<context>-step-N-<descriptor>.png naming.
- Update cross-links in faq.md, edit-description.md, and the bulk-assign
tip to point at the new Tags pages.
- Remove the now-stale Assign Tags section from explore/anomalies.md
and drop the associated assign-light.png and tag-light.png assets.
- Delete the legacy edit-tags-bulk/ asset folder (content migrated).
- Strip screenshots from anomalies/deep-dive/status.md and keep it
conceptual: H1 icon (mdi-alert matching the frontend
icon-anomalies.svg), Status colors reference table sourced from
frontend (consts/anomalies.ts + quasar.variables.scss), and
Open/Archived sub-status reference tables with "Anomaly Status"
column.
- Create anomalies/how-tos/filter-by-status.md as a new how-to with
two sections (Open + Archived), each with three tabs (Explore,
Datastore Anomalies tab, Check Template Anomalies tab) and two
steps per tab (click filter, pick sub-status). Each tab carries
its sub-status reference table for quick lookup.
- Place the 12 captured screenshots under
docs/assets/anomalies/how-tos/filter-by-status/ following the
<context>-<group>-step-N-<descriptor>.png pattern. Mark Container
Level and Field Level views as TODO for future capture.
- Delete the legacy Deep Dive screenshots
(deep-dive/status/{open,archive}-anomalies.png) now that the
page is screenshot-free.
- Add Filter by Status to the How-tos nav before Filter & Sort.
- Move Sort By and Fields content from insights.md to source-record.md
as two new H2 sections placed between Source Record Visualization and
Force Refresh. Refresh and Download already lived in source-record.md;
only adjusted the image paths that were still pointing at
../insights/.
- Replace the full ## Source Records block in insights.md (~65 lines)
with a short pointer paragraph that links to source-record.md, so
insights.md stays focused on the Insights view.
- Reorganize docs/assets/anomalies/deep-dive/source-record/ to follow
the userguide section-prefix naming pattern used in insights/:
- shape-anomaly-highlight.png, record-anomaly-highlight.png
(intro examples)
- sort-by.png, sort-by-options.png (Sort By section)
- fields-*.png (Fields section: button, dropdown, only-anomalous,
hide-all, show-all, show-all-unchecked)
- force-refresh.png, download.png (Force Refresh / Download
sections)
- comparison.png (was is-replica.png, aligns with the section name
Comparison Source Records)
- masked-fields-*.png and visualization.png kept as-is.
- Update all 18 image refs in source-record.md and their alt texts to
match the new filenames.
- Delete the orphan docs/assets/anomalies/deep-dive/insights/source-records.png
left behind by the section removal.
- Create docs/anomalies/deep-dive/description.md covering how the default description is built from failed-check messages, who can edit (Editor team permission), Agent Q AI-suggested descriptions (Use / Regenerate / Dismiss flow), masked-field handling, the archived-anomaly read-only state, History tracking, and a Permissions summary table. - Replace the ## Description block in insights.md with a short pointer paragraph so insights.md stays focused on the Insights view layout. - Add Description to the Deep Dive nav, placed right after Insights. - Page validates against the published UI behavior: Save is disabled when the description is empty or whitespace, Edit/Suggest buttons hide on archived anomalies and for users without Editor permission, and the description renders as plain text with preserved line breaks (no Markdown rendering today).
- Add the "From the Container Anomalies tab" tab to both Open and Archived sections of filter-by-status.md, with 4 new screenshots (container-open-step-1-click-filter, container-open-step-2-view- statuses, container-archived-step-1-click-filter, container- archived-step-2-view-statuses). Update the trailing TODO comment to flag only Field Level as pending. - Restructure filter-and-sort.md around the same entry-point tabs as the other anomaly how-tos (Explore, Datastore, Check Template, Container). Each tab carries its own Sort image + sort table and Filter image + filter table. The previous one-flow structure with filter-1.png / filter-2.png is replaced by 8 context-specific screenshots (explore-sort, explore-filter, datastore-sort, datastore-filter, check-template-sort, check-template-filter, container-sort, container-filter). - Replace the shared FUZZY-SEARCH include-markdown on filter-and-sort with an explicit "Fuzzy search" tip that names the behavior and gives a concrete example (typing "dat" matches "Customer Data"). Validated against frontend filters.vue useFuzzyFilter usage on Datastores, Rules, Containers, Fields, Checks, Tags, and Assignees. - Drop the now-orphan sort-options.png, sort-order.png, filter-1.png, filter-2.png, and fuzzy-anomalies.png; keep the commented-out "Filter by Assignee" / "Assigned subtab" block at the bottom for the future restructure. - Leave a trailing TODO comment on filter-and-sort.md flagging Field Level capture as pending, mirroring filter-by-status.md.
- Add 12 screenshots to docs/assets/anomalies/how-tos/tags/remove-tags/ covering the Remove Tags flow from both entry points (6 Overview + 6 Explore). Filenames follow the Add Tags sister-page pattern with the descriptive suffixes adapted to the remove flow: tags-field, edit-button, tag-picker, remove-tag, tag-unmarked, updated-field. - Replace the 12 placeholder `<!-- TODO: screenshot ... -->` markers in remove-tags.md with real `` references that point at the new files.
Factual corrections validated against frontend and dataplane:
- status.md: rewrite Duplicate vs Discarded info admonition to match
scan re-opening behavior; drop "All" pseudo-status rows from
Open/Archived sub-status tables.
- source-record.md: correct "Weight" sort label to "Importance" and
align setting name with the UI ("Maximum Source Examples per
Anomaly"). Add TODO at top flagging future split of how-to content
out of this Deep Dive (memory exception registered).
Structure:
- filter-and-sort.md: split into Sort options + Filter options H2s with
shared canonical tables outside per-entry-point tabs (drops ~80 lines
of duplication).
Editorial polish across the family:
- Permission terminology (Editor team permission, Admin role).
- Header normalization in sub-status tables.
- Notification clause parity across add/remove/bulk tag how-tos.
- Grammar, bold formatting, 250 MB spacing, "Show audit log" lowercase
match with the UI tooltip.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Restructures the Anomalies section into Deep Dive and How-tos hubs and documents the new Assignees feature end-to-end.
Key Changes
Pages to Test
deep-dive/types.md.:material-plus-circle:icon; two tabs (Anomaly Overview / Anomaly Explore) with identical 6-step flow; singleinfoadmonition at the end covers permissions + notification rule.:material-minus-circle:icon; X-button references are labeled Remove (not "X");notecallout about self-unassignment plustipcross-link to Bulk-Assign.:material-dots-vertical-circle:icon; ellipsis button labeled Bulk menu; Step 6 mentions the in-modal overwrite alert; closingwarningflags the replace semantics.## Sort options+## Filter optionsH2s with shared canonical tables outside per-entry-point tabs; Filter table row 8 documents the Assignees filter; Filter by Assignee / Assigned subtab sections remain wrapped in an HTML comment as a TODO.:material-api:; API docs tip banner immediately after the intro; PUT/PATCH require Author (Editor only for description); dedicated Manage assignees subsection under Update.:material-help-circle-outline:; "Can an Acknowledged anomaly go back to Active?" answers Yes; permissions answer reflects Author-base + Editor-for-description.Editorial polish round
http://localhost:8000/anomalies/deep-dive/status/ — Open/Archived tables no longer list "All" as a status;
!!! infoadmonition rewritten to describe Duplicate vs Discarded in terms of future-scan re-opening (validated against scan re-open logic); table headers normalized toStatus | Description; intros now declare "two sub-statuses" and "four sub-statuses" symmetrically.http://localhost:8000/anomalies/deep-dive/source-record/ — TODO comment at the top flags future refactor of how-to content out of the Deep Dive (memory exception registered); sort table label is Importance (matches frontend); setting referenced consistently as Maximum Source Examples per Anomaly;
***MASKED***literal documented; Editor team permission + Admin role terminology applied.http://localhost:8000/anomalies/how-tos/filter-by-status/ — Table headers normalized to
| No. | Status | Description |; Step 2 reads "colored indicator" (not "icon"); 4 tabs preserved per affirming-capability convention (tables intentionally repeat per entry point).http://localhost:8000/anomalies/how-tos/tags/add-tags/ — Lead now includes API link; Step 3 reads "Start typing to narrow the list"; Step 4 uses "Select"; admonition includes current-assignee notification clause matching the assignee how-tos.
http://localhost:8000/anomalies/how-tos/tags/remove-tags/ — Lead now includes API link; admonition includes current-assignee notification clause.
http://localhost:8000/anomalies/how-tos/tags/bulk-edit/ — Step 11 mentions in-app notification for current assignees of each anomaly.
Legacy redirects still resolve: `/anomalies/status/`, `/anomalies/types/`, `/anomalies/fingerprints/`, `/anomalies/details/insights/`, `/anomalies/details/source-record/`, and `/anomalies/manage-anomalies//` should all land on their new `deep-dive/` or `how-tos/` URLs.