Updated documentation for current features#151
Conversation
There was a problem hiding this comment.
Pull request overview
Documentation refresh for the SoA Workbench UI and setup guidance, primarily updating the “Help” page and README to reflect current navigation and features.
Changes:
- Expanded the in-app Help page with updated step-by-step workflow across Study creation, matrix setup, and USDM export.
- Updated README to describe current UI flows and adjusted install/setup instructions.
- Simplified
.github/copilot-instructions.mdpre-commit section to match current tooling (ruff + pytest).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 12 comments.
| File | Description |
|---|---|
src/soa_builder/web/templates/help.html |
Updates end-user help steps for creating/configuring a study and SoA matrix. |
README.md |
Updates project description, install steps, and UI usage notes. |
.github/copilot-instructions.md |
Updates pre-commit documentation to reflect current hooks. |
You can also share your feedback on Copilot code review. Take the survey.
| <li>There are four configurations available | ||
| <ul> | ||
| <li>Set a <strong>name</strong> (e.g., "Week 1", "Day 1")</li> | ||
| <li><strong>IMPORTANT:</strong> Set <strong>Member of Timeline</strong> to the timeline created in Step 1</li> | ||
| <li>Optionally link to an encounter from Step 2</li> | ||
| <li>Optionally link to an Epoch</li> | ||
| <li>Schedule Timelines</li> | ||
| <li>Scheduled Activity Instances</li> | ||
| <li>Scheduled Decision Instances</li> | ||
| <li>Condition Assignments</li> | ||
| <li>Timings</li> | ||
| </ul> |
There was a problem hiding this comment.
The text says "There are four configurations available" but the list below contains five items (Schedule Timelines, Scheduled Activity Instances, Scheduled Decision Instances, Condition Assignments, Timings). Update the count or adjust the list so they match.
| <li>Click <strong>Transition Rules</strong> in the menu navigation menu</li> | ||
| </ul> | ||
| </li> | ||
| <li> | ||
| <h3>USDM JSON can also be generated</h3> | ||
| <ul> | ||
| <li>Click <strong>Generate USDM JSON</strong> in the menu navigation menu</li> |
There was a problem hiding this comment.
Wording duplication: "menu navigation menu" should be simplified (e.g., just "navigation menu").
| <li>Click <strong>Transition Rules</strong> in the menu navigation menu</li> | |
| </ul> | |
| </li> | |
| <li> | |
| <h3>USDM JSON can also be generated</h3> | |
| <ul> | |
| <li>Click <strong>Generate USDM JSON</strong> in the menu navigation menu</li> | |
| <li>Click <strong>Transition Rules</strong> in the navigation menu</li> | |
| </ul> | |
| </li> | |
| <li> | |
| <h3>USDM JSON can also be generated</h3> | |
| <ul> | |
| <li>Click <strong>Generate USDM JSON</strong> in the navigation menu</li> |
| - More options and parameters for configuring the USDM classes are available through these navigation links. | ||
| - Add Scheduled Activity instances (columns) and activities (rows) to create an SoA matrix on the edit page for a Study; click cells to toggle status (blank -> X -> blank). 'O' values are not surfaced in the UI; clearing removes the cell row. | ||
| - Use export buttons (to be added) for XLSX output of the Matrix. | ||
| - View avialable biomedical concepts via the "Biomedical Concepts" navigation link to render a table of concept codes, titles and API links (cached; force refresh available). |
There was a problem hiding this comment.
Typo: "avialable" should be "available".
| - View avialable biomedical concepts via the "Biomedical Concepts" navigation link to render a table of concept codes, titles and API links (cached; force refresh available). | |
| - View available biomedical concepts via the "Biomedical Concepts" navigation link to render a table of concept codes, titles and API links (cached; force refresh available). |
| - Add Scheduled Activity instances (columns) and activities (rows) to create an SoA matrix on the edit page for a Study; click cells to toggle status (blank -> X -> blank). 'O' values are not surfaced in the UI; clearing removes the cell row. | ||
| - Use export buttons (to be added) for XLSX output of the Matrix. | ||
| - View avialable biomedical concepts via the "Biomedical Concepts" navigation link to render a table of concept codes, titles and API links (cached; force refresh available). |
There was a problem hiding this comment.
This list item has inconsistent indentation (extra leading space before -), which can break Markdown list rendering. Align indentation with the surrounding bullets.
| <li>Create visits (e.g., "Visit 1", "Visit 2", "Screening"</quote>)</li> | ||
| <li>These will appear as column headers in the Matrix</li> | ||
| <li> | ||
| A basic Schedule of Activity Matrix can be created on the landing lage once a study is created. |
There was a problem hiding this comment.
Typo: "landing lage" should be "landing page".
| A basic Schedule of Activity Matrix can be created on the landing lage once a study is created. | |
| A basic Schedule of Activity Matrix can be created on the landing page once a study is created. |
| Recommended: editable install for development. | ||
| ```bash | ||
| python3 -m venv .venv | ||
| source .venv/bin/activate | ||
| pip install -e . | ||
| pip install -r requirements.txt | ||
| pre-commit install | ||
| pre-commit run --all-files | ||
| ``` |
There was a problem hiding this comment.
The installation steps say "editable install for development", but pip install -r requirements.txt does not install the local package (so soa-builder-web / soa-builder console scripts likely won't be available). Consider switching back to an editable install (and including dev extras if needed), or adjust the subsequent instructions to match how users should run the app.
| - Create a new Schedule of Activities for a study or access an existing one. | ||
| - When a study is chosen, additional navigation links are available in the navigation menu that are unique to the Study context. | ||
| - More options and parameters for configuring the USDM classes are available through these navigation links. | ||
| - Add Scheduled Activity instances (columns) and activities (rows) to create an SoA matrix on the edit page for a Study; click cells to toggle status (blank -> X -> blank). 'O' values are not surfaced in the UI; clearing removes the cell row. |
There was a problem hiding this comment.
Markdown list formatting: these sub-bullets use tab indentation, which can render inconsistently across Markdown viewers. Prefer consistent space indentation for nested lists.
| <ol> | ||
| <li> | ||
| <h3>Create a Schedule Timeline (container)</h3> | ||
| <h3>Create a new Schedule of Activties on the landing page.</h3> |
There was a problem hiding this comment.
Typo in heading: "Activties" should be "Activities".
| <h3>Create a new Schedule of Activties on the landing page.</h3> | |
| <h3>Create a new Schedule of Activities on the landing page.</h3> |
| <li> | ||
| A basic Schedule of Activity Matrix can be created on the landing lage once a study is created. | ||
| </li> | ||
| <li>Add Scheduled Instances to create coluuns for the SOA Matrix</li> |
There was a problem hiding this comment.
Typo: "coluuns" should be "columns".
| <li>Add Scheduled Instances to create coluuns for the SOA Matrix</li> | |
| <li>Add Scheduled Instances to create columns for the SOA Matrix</li> |
| A basic Schedule of Activity Matrix can be created on the landing lage once a study is created. | ||
| </li> | ||
| <li>Add Scheduled Instances to create coluuns for the SOA Matrix</li> | ||
| <li>Add Activites to create rows for the SOA Matrix</li> |
There was a problem hiding this comment.
Typo: "Activites" should be "Activities".
Some documentation updates for the latest features.