zalando/restful-api-guidelines

Editorial: Uniform Layout and Naming of Hints, Remarks, Exceptions etc.

Open

#660 ouverte le 18 mai 2021

Voir sur GitHub
 (11 commentaires) (0 réactions) (1 assigné)CSS (356 forks)batch import
editorialenhancementhelp wanted

Métriques du dépôt

Stars
 (1 984 stars)
Métriques de merge PR
 (Merge moyen 3j 12h) (2 PRs mergées en 30 j)

Description

We use different layout formats for standard guideline elements like 'Exception:', 'Hint:', 'Note:', 'Remark:', 'Example:', 'Tip', 'Reasoning:', 'Warning:', 'Important:', 'Caution:'. Additionally, the elements are partially redundant with unclear 'didactic purpose'. Let us reduce the elements to a minimal set with clear purpose and uniform layout. It will contribute to readability and efficient consumption by API builders. Examples:

Guide contributeur

Direction de recherche
L'objectif de cette issue est de standardiser la mise en page et la dénomination des éléments éditoriaux tels que les astuces, notes et exceptions dans les directives d'API RESTful. Tout d'abord, examinez les exemples fournis (par exemple #101, #116, #104, #114) pour voir les incohérences actuelles. Ensuite, lisez les commentaires pour les suggestions de la communauté sur un ensemble minimal d'éléments et un format uniforme. Le travail implique la modification de plusieurs fichiers Markdown, chacun correspondant à une règle de directive. Identifiez toutes les instances de ces éléments et proposez une convention de dénomination cohérente (par exemple "Note :", "Avertissement :", etc.) et une mise en page visuelle uniforme. Aucune modification de code n'est nécessaire ; concentrez vous sur le texte et la mise en forme. La structure du dépôt peut être explorée dans le répertoire ` guidelines`.
Stack technique
Aucun
Domaine
documentation
Type d'issue
Documentation
DifficultéDifficulté estimée pour un nouveau contributeur, de 1 pour un très petit changement à 5 pour un travail expert.
2
Temps estiméFourchette de temps approximative pour investiguer, implémenter, tester et préparer une pull request.
Moins d'une heure
Statut d'activitéDisponibilité apparente de l'issue : fraîche, active, ancienne, bloquée ou en attente d'un mainteneur.
Active
ClartéClarté avec laquelle l'issue explique le changement attendu, les critères d'acceptation et la prochaine étape.
Claire
Prérequis
Aucun
Accessibilité débutantScore de 1 à 100 estimant l'accessibilité de cette issue pour un premier contributeur.
85