Add Definition and Terminology docs for 3.1 - #89
Conversation
Publish the Questionnaire, Questionnaire Response Template, Valueset, Observation Definition, Specimen Definition, Activity Definition and Charge Item Definition modules from the care_docs sources. Refreshes the seven definition concepts and adds twenty-two flows under a new Definitions category in the 3.1 flows sidebar.
Deploying coredocs with
|
| Latest commit: |
1810a0e
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://0a096f5a.coredocs.pages.dev |
| Branch Preview URL: | https://docs-definitions-modules.coredocs.pages.dev |
Co-authored-by: aravindm4 <92707064+aravindm4@users.noreply.github.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Warning
Threat Detection Engine Failure — The analysis engine could not complete. This is a tooling failure, not a security finding.
What happened
The threat detection results could not be parsed.
Review the workflow run logs for details.
Docs review — Definition and Terminology modules (3.1)
This is a large, unusually consistent change. The 22 flows all carry the flow template's sections in the template's order, the concepts all follow Definition → Key Attributes → Status → Related, and the language is clean STE — short sentences, active voice, one instruction per step. Slugs are kebab-case and the flow slugs are verb phrases. I found no corruption, no {#...} heading ids, no bare braces, and no code, endpoints or permission slugs leaking into the user-facing layers.
Verified against the Care source
I checked every permission display name used in the flow tables against care/security/permissions/. All of them are exact:
Can Create/Update Questionnaires,Can Create/Update Questionnaire Response Templates,Can Read Questionnaire Response TemplatesCan Create Observation Definition on Facility,Can Create Specimen Definition on Facility,Can Read Specimen DefinitionCan Create Charge Item Definition on Facility,Can Read Charge Item DefinitionCan Create Activity Definition on Facility,Can Write Service Request on Facility
The manage-organizations flow citing Can Create/Update Questionnaires is also right — QuestionnaireViewSet.set_organizations calls can_write_questionnaire, not can_manage_questionnaire.
I resolved all 111 relative links against the tree as it will be after this PR. Every one resolves, including the cross-domain links out to Clinical and Billing. The flow sidebar is correctly updated: all 22 new flows appear in the Definitions category in version-3.1-sidebars.json, none is missing.
What I raised inline
- Mirroring (checklist 11) — the significant one. Everything lands in
version-3.1only. The conventions require 3.0 and 3.1 to stay byte-identical, so the flows tree, the seven concepts, and the 3.0 sidebar all need the same change. - Sibling-relative links (12) — the concepts consistently write
../../concepts/definitions/x.mdxfor a file in their own folder. It resolves, so the build is green, but the conventions call for./x.mdxand../<domain>/<slug>.mdx. - An invented
## Accesssection (8) onquestionnaire.mdx, with the same content appearing as### Who can change a valuesetand### Who can see a templateelsewhere. Not a template section, and not named consistently across the three. - FHIR narration (7) — one leftover note stating that no FHIR R5 resource applies to the response template.
Could not verify
- The UI labels, toast messages and button names in the flows ("Create Questionnaire", "Add Activity Definition", "Questionnaire created successfully!", "At least one organization must be selected"). These read as authentic and consistently cased, but I did not trace each one to
care_fepublic/locale/en.json. Worth a spot check before merge, particularly the exact toast wording in the Expected Outcome sections. - Whether the
DescriptionandUsagefields really are mandatory on the activity definition form —create-activity-definition.mdxmarks both Required, which is unusual for free-text fields.
None of this is merge-blocking apart from the mirroring gap, which will leave the 3.0 version of the site without any of these pages.> Generated by Docs Reviewer for #89 · opus50 · 201.8 AIC · ⊞ 11K
| A **questionnaire response template** is a saved set of medications and service requests. You apply the template when you fill a questionnaire. The template prevents the entry of the same orders for each patient. You can change every value that the template fills in. | ||
|
|
||
| A response template is a Care-specific authoring convenience, not a FHIR resource. The key thing to understand is that it is a recipe, not a record. Nothing in a template touches a patient until a clinician applies it and submits the resulting [questionnaire response](../clinical/questionnaire-response.mdx) — only then are real orders, requests, and observations created. Editing or deleting a template never changes responses already submitted from it. | ||
| Note: A questionnaire response template is a convenience feature of Care. No FHIR R5 resource applies to it. |
There was a problem hiding this comment.
Checklist item 7 (FHIR): linking the FHIR page is good, narrating the mapping is not. Note: A questionnaire response template is a convenience feature of Care. No FHIR R5 resource applies to it. explains an absence of a mapping, which is exactly the kind of FHIR narration the rule removes. Delete the note — the reader does not need it.
| | `can_read_questionnaire` | View questionnaire definitions, list them, and see the organizations a questionnaire is scoped to | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist, Admin (role org), Manager (role org), Member (role org) | | ||
| | `can_submit_patient_questionnaire` | Submit a questionnaire about a patient (no encounter) | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator | | ||
| | `can_submit_encounter_questionnaire` | Submit a questionnaire against a patient encounter | Staff, Doctor, Nurse, Admin, Facility Admin | | ||
| ## Access |
There was a problem hiding this comment.
Checklist item 8 (template conformance): ## Access is not a section of the concept template, which is Definition -> Key Attributes -> (Status) -> Related. Two other concepts in this PR invent the same section under different names (### Who can change a valueset, ### Who can see a template), so the set is also inconsistent. Fold the access statement into Key Attributes or the Definition, or drop it — permission depth belongs in the reference doc.
| - Flow: [Clone a questionnaire](../../flows/definitions/questionnaire/clone-questionnaire.mdx) | ||
| - Concept: [Questionnaire Response](../../concepts/clinical/questionnaire-response.mdx) | ||
| - Concept: [Questionnaire Response Template](../../concepts/definitions/questionnaire-response-template.mdx) | ||
| - Concept: [Valueset](../../concepts/definitions/valueset.mdx) |
There was a problem hiding this comment.
Checklist item 12 (links): links from a concept back into its own folder should be sibling-relative. ../../concepts/definitions/valueset.mdx walks up two levels and back down into the folder the file already lives in. Use ./valueset.mdx (and ../clinical/questionnaire-response.mdx for the cross-domain one) — the same pattern applies to every ../../concepts/... link added across the seven concept pages.
| --- | ||
|
|
||
| # Value Set | ||
| # Valueset |
There was a problem hiding this comment.
Checklist item 14 (terminology): the title changes from "Value Set" to "Valueset", but references/definitions/valueset.mdx and several other pages still say "ValueSet". One term for one thing across every file in scope — either keep the existing spelling or update the reference doc and the other mentions in the same PR.
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| # Create a questionnaire |
There was a problem hiding this comment.
Checklist item 11 (mirroring): the conventions say versioned_docs/version-3.0/ and version-3.1/ are kept byte-identical. This PR adds 22 flows and rewrites 7 concepts in 3.1 only, and updates versioned_sidebars/version-3.1-sidebars.json alone. Mirror the whole flows/definitions/ tree and the seven concept files into version-3.0, and add the same Definitions category to versioned_sidebars/version-3.0-sidebars.json.
| - Concept: [Specimen Definition](../../concepts/definitions/specimen-definition.mdx) | ||
| - Concept: [Observation Definition](../../concepts/definitions/observation-definition.mdx) | ||
| - Concept: [Charge Item Definition](../../concepts/definitions/charge-item-definition.mdx) | ||
| - Concept: [Service Request](../../concepts/clinical/service-request.mdx) |
There was a problem hiding this comment.
Checklist item 12 (links): same sibling-relative issue as questionnaire.mdx. ../../concepts/clinical/service-request.mdx should be ../clinical/service-request.mdx, and the three ../../concepts/definitions/... links should be ./specimen-definition.mdx, ./observation-definition.mdx, ./charge-item-definition.mdx.
What
Publishes the seven Definition and Terminology modules from
care_docsinto the docs site (version 3.1). 22 flows and 7 refreshed concepts.Adds a
Definitionscategory to the 3.1 flows sidebar with the seven modules nested under it. All seven concepts replace the existing pages underconcepts/definitions/.Frontmatter
Only Observation Definition had any frontmatter, and its
domainreaddefinition-and-terminology, which does not exist on the site — that would have created a new domain and orphaned the existing page. It is corrected todefinitions, matching where all seven concepts already live.The other six concepts and all twenty-two flows had no frontmatter, so
domain,module,slugandsidebar_positionwere added. Concept positions follow the existing site order.Flow titles were converted from "How to Create a Questionnaire" to "Create a questionnaire".
Concept titles
Two existing pages change title, since the authored title is published as written:
Note for reviewers
All seven concepts are replaced, not extended.
product-knowledge.mdxhas no counterpart incare_docsand is untouched.These modules link out to Clinical (Service Request, Specimen, Questionnaire Response) and Billing (Charge Item). All links resolve in the build.
Verification
Docusaurus build passes for both
enandmllocales.