Docs: should HTTP methods be in code tags
Problem to solve
How should we style the various methods for HTTP requests? The methods are:
HTTP GET
HTTP POST
HTTP PUT
HTTP DELETE
HTTP PATCH
There are several options:
- Standard text: HTTP GET request
- Verb wrapped in backticks: HTTP
GET
request - Entire phrase wrapped in backticks:
HTTP GET
request
We have no consistent guidance from either the Microsoft Manual of Style, or the Google Developer Style Guide:
-
Google uses this style: source more examples
- an HTTP
400 Bad Request
status code - an HTTP
2xx
or400
status code
- an HTTP
-
Microsoft does not provide a specification in their style guide, but in this Azure documentation page the method name and number are written in standard text, and the name of the header is written in parentheses:
If a PUT method creates a new resource, it returns HTTP status code 201 (Created), as with a POST method. If the method updates an existing resource, it returns either 200 (OK) or 204 (No Content).
Further details
Related to #209010 (closed) which attempts to set up an acronyms test for Vale, encouraging the writer to spell out abbreviations on their first use. Putting the method names in all caps causes the acronyms test to think it's an acronym, and the decision here will help determine 1) if method names should be allowed as acronyms and 2) if we should craft a separate test requiring these methods to be in backticks.