API Documentation standardization
Problem to solve
The API docs have been edited by so many people over such a long time, that there are signification differences from page to page. These should be standardized and aligned ASAP.
Further details
Examples that need improving:
- Invalid use of code style in heading: https://docs.gitlab.com/ee/api/templates/gitignores.html.
- Poor level 1 header: https://docs.gitlab.com/ee/api/templates/gitlab_ci_ymls.html.
- Note about version intro not standard: https://docs.gitlab.com/ee/api/access_requests.html.
- Doesn’t introduce itself: https://docs.gitlab.com/ee/api/group_clusters.html.
Examples that are OK:
- https://docs.gitlab.com/ee/api/applications.html
- https://docs.gitlab.com/ee/integration/oauth_provider.html
- https://docs.gitlab.com/ee/api/avatar.html
- https://docs.gitlab.com/ee/api/award_emoji.html
Proposal
A list of standard rules for api documentation needs to be finalized and implemented as well.