The current version of the OAD style guide prepared as part of T398348 contains recommendations for wording that should be used in critical OAD fields, such as summaries and descriptions, alongside some extra information. However, it doesn't incorporate requirements resulting from the OpenAPI explorer work (T400174) and the upcoming linter work (TBA). Additionally, it doesn't yet accommodate specific requirements related to internationalization of OAD content.
This task collects all work related to OAD style guide improvements resulting from the above.
Plan
- Improve the style guide based on feedback from different stakeholders
- Identify sections that could use additional instructions (e.g.
is the section about grouping endpoints clear?- fixed) - T410087: Create example/test OAD
- Add recommendations for messages about endpoint deprecations (related to T405038)
- Add recommendations for documenting enum values
- Identify sections that could use additional instructions (e.g.
- Add the necessary information based on explorer requirements:
- Establish good practices for the main info.description field (intersection with IA work)
- Include instructions on the correct way of linking to external resources (changelog, landing page, news)
- Build a list of the required OAD fields (intersection with linter work)
- Review current recommendations for compatibility with common translation patterns