Improve README files with structure, badges, accessibility, and navigation per documentation standards - #3
Draft
chikamsoachumsft with Copilot wants to merge 2 commits into
Draft
Conversation
… sections per custom instructions Co-authored-by: chikamsoachumsft <224665915+chikamsoachumsft@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Improve Readme with custom instructions
Improve README files with structure, badges, accessibility, and navigation per documentation standards
Feb 25, 2026
There was a problem hiding this comment.
Pull request overview
This PR updates the repository’s README documentation to better onboard new users by improving structure, adding key sections/tables, and replacing generic image alt text with descriptive alternatives for accessibility.
Changes:
- Expanded the root
README.mdwith badges, features, prerequisites, quick start guidance, an exercises table, and a configuration parameters table. - Restructured
Exercise00-Setup/README.mdto include objective/prerequisites/validation and improved image alt text. - Updated Exercise 01–03 READMEs to replace generic
alt text with descriptive alt text.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds a more complete project overview, quick start flow, and parameter documentation. |
| Exercise00-Setup/README.md | Adds objective/prereqs/validation and improves accessibility of screenshots. |
| Exercise01-Claims/README.md | Replaces generic screenshot alt text with descriptive alt text. |
| Exercise02-Observations/README.md | Replaces generic screenshot alt text with descriptive alt text. |
| Exercise03-Patients/README.md | Replaces generic screenshot alt text with descriptive alt text. |
Comment on lines
15
to
+17
| * Fork microsoft/AzureSynapseEndToEndDemo project to your local github account. Make sure to check "Copy the main branch only". | ||
|
|
||
|  | ||
|  |
There was a problem hiding this comment.
This step instructs readers to fork "microsoft/AzureSynapseEndToEndDemo", but the prerequisites above say they should fork "this repository". This inconsistency can confuse users and also affects which repo the Deploy-to-Azure experience will configure for Git integration. Align the wording (and owner/org) with the intended repo for this documentation.
|
|
||
|
|
||
| # STEP 1: Parameter Setup | ||
| Prior to running the observations pipeline (FHIR_Pipeline4Observation_Spark_OC) you will need to set the pipeline parameters to use the artifact names you chose during deployment. Go to the integrate hub, expand the obsevation folder, and select the pipeline to open it. |
There was a problem hiding this comment.
Typo: "obsevation folder" should be "observation folder".
Suggested change
| Prior to running the observations pipeline (FHIR_Pipeline4Observation_Spark_OC) you will need to set the pipeline parameters to use the artifact names you chose during deployment. Go to the integrate hub, expand the obsevation folder, and select the pipeline to open it. | |
| Prior to running the observations pipeline (FHIR_Pipeline4Observation_Spark_OC) you will need to set the pipeline parameters to use the artifact names you chose during deployment. Go to the integrate hub, expand the observation folder, and select the pipeline to open it. |
|  | ||
|
|
||
|
|
||
| * We plan to eventually load this data into Dedicated SQL Pool across 2 tables representing Patient Addresses and Patient Indentifiers. We need to extract the data needed for each table, clean it, and write it back to ADLS. The second activity in our pipeline handles all of this inside a Data Flow Activity. This could have been done in a Spark notebook like the previous 2 activities, but this will let you compare the two methods. |
There was a problem hiding this comment.
Typo: "Patient Indentifiers" should be "Patient Identifiers".
Suggested change
| * We plan to eventually load this data into Dedicated SQL Pool across 2 tables representing Patient Addresses and Patient Indentifiers. We need to extract the data needed for each table, clean it, and write it back to ADLS. The second activity in our pipeline handles all of this inside a Data Flow Activity. This could have been done in a Spark notebook like the previous 2 activities, but this will let you compare the two methods. | |
| * We plan to eventually load this data into Dedicated SQL Pool across 2 tables representing Patient Addresses and Patient Identifiers. We need to extract the data needed for each table, clean it, and write it back to ADLS. The second activity in our pipeline handles all of this inside a Data Flow Activity. This could have been done in a Spark notebook like the previous 2 activities, but this will let you compare the two methods. |
| 1. **Fork this repository** to your own GitHub account. Make sure to check **Copy the main branch only**. | ||
| 2. **Deploy to Azure** by clicking the button below. This deploys the Synapse workspace, Dedicated SQL Pool, Spark Pool, and all pipeline artifacts. | ||
|
|
||
| [](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2FAzureSynapseEndToEndDemo%2Fmain%2FARMTemplate%2Fazuredeploy.json) |
There was a problem hiding this comment.
The "Deploy to Azure" link hardcodes the ARM template URL to the microsoft/AzureSynapseEndToEndDemo repo. Since this README otherwise points to this repo (e.g., license badge / issues), users who fork this repository may unintentionally deploy from a different source. Consider updating the raw GitHub URL to this repository (or clarifying that deployment always uses the upstream template).
Suggested change
| [](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2FAzureSynapseEndToEndDemo%2Fmain%2FARMTemplate%2Fazuredeploy.json) | |
| [](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fchikamsoachumsft%2FAzureSynapseEndToEndDemo%2Fmain%2FARMTemplate%2Fazuredeploy.json) |
Comment on lines
+1
to
+3
| ## Exercise 00 - Setup: Deploy Azure Synapse Demo in Your Azure Environment | ||
|
|
||
| ### Pre-requisites to Deploy Synapse end-to-end Demo | ||
| ### Objective |
There was a problem hiding this comment.
This exercise README starts with an H2 ("##") and then uses H3s, which breaks the typical heading hierarchy and is inconsistent with the other exercise READMEs (which start with an H1). Consider making the top heading an H1 ("#") to improve accessibility and consistency.
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
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.
The root README was minimal (title + architecture image + bare link list), lacking the structure needed for new users to orient quickly. Exercise READMEs had generic
alt text throughout, violating accessibility standards.Root
README.mdStorageName,DatabaseName,ServerName,SparkPoolName,DatasetSize) with examplesExercise00-Setup/README.mdExercise 01–03 READMEs
instances with descriptive alt text accurately reflecting each screenshot's contentOriginal prompt
Work item: AB#251
Created via Azure DevOps
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.