Skip to main content

IPA-3 IPA Style and Guidance

IPAs are most useful when they are clear and concise and cover a single topic or inquiry well. In the same way that IPAs describe consistent patterns and style for use in APIs, they also follow consistent patterns and style.

State

Adopt

Guidance​

  • IPAs must cover a single, discrete topic and provide clear, actionable guidance
  • IPAs must not duplicate or contradict guidance in another IPA
  • IPAs may also cover what not to do but should not cover only antipatterns

IPA Structure​

  • IPAs should begin with an introduction (with no additional heading).
  • IPAs must include the current state, formatted as admonition.
    • Valid states are listed in IPA-1
  • The guidance section may include subsections that elaborate further on the details
  • If necessary, the IPA may include a “Further Reading” section after guidance

Requirement Keywords​

  • IPAs should use the following requirement level keywords: "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY", which are to be interpreted as described in RFC 2119
  • When using these terms in IPAs, they must be lower-case and bold
  • These terms should not be used in other ways