State differences between XML and Markdown formats

Author: owen-mc

docs/query-help-style-guide.md

@@ -20,7 +20,7 @@ Query help files must have the same base name as the query they describe and mus
 
 ### File structure and layout
 
-Query help files can be written in either a custom XML format (with a `.qhelp` extension) or in Markdown (with a `.md` extension). Both formats are supported by the CodeQL documentation tooling.
+Query help files can be written in either a custom XML format (with a `.qhelp` extension) or in Markdown (with a `.md` extension). Both formats are supported by the CodeQL documentation tooling. There are a few minor differences, noted in the section `Differences between XML and markdown formats` below.
 
 #### Markdown query help files
 
@@ -126,7 +126,7 @@ For example:
 
 ### Referencing potential security weaknesses
 
-If your query checks code for a CWE weakness, you should use the `@tags` element in the query file to reference the associated CWEs, as explained [here](query-metadata-style-guide.md). When you use these tags, a link to the appropriate entry from the [MITRE.org](https://cwe.mitre.org/scoring/index.html) site will automatically appear as a reference in the output HTML file.
+If your query checks code for a CWE weakness, you should use the `@tags` element in the query file to reference the associated CWEs, as explained [here](query-metadata-style-guide.md). When you use these tags in a query help file in the custom XML format, a link to the appropriate entry from the [MITRE.org](https://cwe.mitre.org/scoring/index.html) site will automatically appear as a reference in the output HTML file.
 
 ## Validating query help files
 
@@ -143,6 +143,11 @@ Please include the query help files (and any associated code snippets) in your p
 
 More information on how to test your query help files can be found [within the documentation](https://docs.github.com/en/code-security/codeql-cli/using-the-codeql-cli/testing-query-help-files)
 
+## Differences between XML and markdown formats
+
+1. The XML format allows for the contents of other files to be included in the output generated by processing the file, as mentioned in the section `Code examples`. This is not possible with the Markdown format.
+2. When using the XML format, references are added to the output HTML file based on CWE tags, as mentioned in the section `Referencing potential security weaknesses`.
+
 ## Query help example
 
 The following example is a query help file for a query from the standard query suite for Java, shown in both Markdown and XML formats.