zalando/restful-api-guidelines

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

Open

#660 aperta il 18 mag 2021

Vedi su GitHub
 (11 commenti) (0 reazioni) (1 assegnatario)CSS (356 fork)batch import
editorialenhancementhelp wanted

Metriche repository

Star
 (1984 star)
Metriche merge PR
 (Merge medio 3g 12h) (2 PR mergiate in 30 g)

Descrizione

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:

Guida contributor

Direzione di ricerca
L'obiettivo di questo issue è standardizzare il layout e la denominazione degli elementi editoriali come suggerimenti, note ed eccezioni nelle linee guida delle API RESTful. Innanzitutto, rivedi gli esempi forniti (ad es. #101, #116, #104, #114) per vedere le attuali incongruenze. Quindi, leggi i commenti per i suggerimenti della comunità su un set minimo di elementi e un formato uniforme. Il lavoro comporta la modifica di più file Markdown, ciascuno corrispondente a una regola delle linee guida. Identifica tutte le istanze di questi elementi e proponi una convenzione di denominazione coerente (ad es. "Nota:", "Avviso:", ecc.) e un layout visivo uniforme. Non sono necessarie modifiche al codice; concentrati su testo e formattazione. La struttura del repository può essere esplorata nella directory ` guidelines`.
Tech stack
Nessuno
Dominio
documentation
Tipo issue
Documentazione
DifficoltàQuanto dovrebbe essere impegnativa per un nuovo contributor.
2
Tempo stimatoTempo stimato per completare e verificare uno scope piccolo.
Meno di 1 ora
Stato attivitàQuanto è probabile che la issue sia ancora attiva e reviewable.
Attiva
ChiarezzaQuanto chiaramente la issue descrive problema, scope e risultato atteso.
Chiara
Prerequisiti
Nessuno
Adatta ai principiantiQuanto la issue è adatta a contributor alla prima esperienza.
85