To ensure everyone is aware of a consistent set of criteria for inclusion of content into the specifications, we define here a series of gates that a change must pass through to be acceptable.
Changes should be assessed against these gates at all stages of its development but it is the Commit Lead who is ultimately accountable for accepted changes meeting the criteria defined here.
Language
Added content is always in International English
Media formats
Where content is presented in a media format other than text, it must be one of the following, in order of preference:
Mermaid.js should be used for process, web sequence etc diagrams
The built-in OpenAPI module to be used for presenting OpenAPI documents.
Jpg images may be used but must always include alt text explaining the image
Always consider the source of the media. It should always be stored within the versioned git repository to ensure changes can be viewed and that it won’t change inadvertently. Media uploaded to GitBook will automatically be added to the versioned git repository.
Hyperlinks
Always consider whether the target resource a hyperlink is pointing to will change outside the versioning we do for the specification. Does the specification rely on a particular version of the target resource?