zalando/restful-api-guidelines

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

Open

#660 geöffnet am 18. Mai 2021

Auf GitHub ansehen
 (11 Kommentare) (0 Reaktionen) (1 zugewiesene Person)CSS (356 Forks)batch import
editorialenhancementhelp wanted

Repository-Metriken

Stars
 (1.984 Stars)
PR-Merge-Metriken
 (Durchschn. Merge 3T 12h) (2 gemergte PRs in 30 T)

Beschreibung

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:

Contributor Guide

Research-Richtung
Das Ziel dieses Issues ist es, das Layout und die Benennung von redaktionellen Elementen wie Hinweisen, Notizen und Ausnahmen in den RESTful API Richtlinien zu standardisieren. Überprüfen Sie zunächst die bereitgestellten Beispiele (z. B. #101, #116, #104, #114), um die aktuellen Inkonsistenzen zu sehen. Lesen Sie dann die Kommentare, um Vorschläge der Community zu einem minimalen Satz von Elementen und einem einheitlichen Format zu erhalten. Die Arbeit umfasst die Bearbeitung mehrerer Markdown Dateien, die jeweils einer Richtlinienregel entsprechen. Identifizieren Sie alle Instanzen dieser Elemente und schlagen Sie eine konsistente Benennungskonvention (z. B. „Hinweis:“, „Warnung:“ usw.) und ein einheitliches visuelles Layout vor. Es sind keine Codeänderungen erforderlich; konzentrieren Sie sich auf Text und Formatierung. Die Struktur des Repositorys kann im Verzeichnis ` guidelines` erkundet werden.
Tech Stack
Keine
Domain
documentation
Issue Type
Dokumentation
SchwierigkeitGeschätzte Implementierungsschwierigkeit für neue Contributors, von 1 für sehr kleine Änderungen bis 5 für Expertenarbeit.
2
Geschätzte ZeitEin grober Zeitrahmen, um zu recherchieren, zu implementieren, zu testen und einen Pull Request vorzubereiten.
Unter 1 Stunde
AktivitätsstatusWie verfügbar das Issue gerade wirkt: frisch, aktiv, stale, blockiert oder wartet auf Maintainer-Input.
Aktiv
KlarheitWie klar das Issue die erwartete Änderung, Akzeptanzkriterien und den nächsten Schritt erklärt.
Klar
Voraussetzungen
Keine
EinsteigerfreundlichkeitEin Score von 1 bis 100, der schätzt, wie zugänglich dieses Issue für First-Time Contributors ist.
85