RFC: Document Article Usage Rules

[KrisSimon]

Problem

ARO uses English articles (a/an/the) but inconsistent usage appears in examples.

Examples

(* Correct: 'an' before vowel sound *)
<Return> an <OK: status> with <users>.
(* From: UserService/users.aro:8 *)

(* Correct: 'a' before consonant sound *)
<Return> a <Created: status> with <user>.
(* From: UserService/users.aro:28 *)

(* Edge case: acronyms *)
<Return> an <OK: status>...    (* 'O' sounds like "oh" - vowel sound *)

Analysis

The codebase is mostly correct, following English phonetic rules:

• an before vowel sounds (an OK, an HTTP...)
• a before consonant sounds (a Created, a NoContent...)

Edge Cases

Word	Article	Reason
OK	an	"oh-kay" starts with vowel sound
HTTP	an	"aitch-tee..." starts with vowel sound
URL	a	"you-are-ell" starts with consonant sound
Created	a	Starts with consonant

Proposed Solution

Document in style guide:

### Article Usage

Use English phonetic rules for articles:

| Sound | Article | Examples |
|-------|---------|----------|
| Vowel sound | an | an OK, an HTTP, an hour |
| Consonant sound | a | a Created, a URL, a user |

Note: Use the **sound**, not the letter. "URL" starts with "Y" sound, so use "a URL".

Impact

• Documentation addition only
• No code changes required
• Helps non-native English speakers

Questions

1. Should the parser enforce article rules?
2. Are articles semantically significant or just style?
3. Should articles be optional for terseness?

[KrisSimon]

It's an issue, now.