zalando/restful-api-guidelines

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

Open

#660 aberto em 18 de mai. de 2021

Ver no GitHub
 (11 comments) (0 reactions) (1 assignee)CSS (356 forks)batch import
editorialenhancementhelp wanted

Métricas do repositório

Stars
 (1.984 stars)
Métricas de merge de PR
 (Mesclagem média 3d 12h) (2 fundiu PRs em 30d)

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:

Guia do colaborador

Direção de pesquisa
O objetivo desta issue é padronizar o layout e a nomenclatura de elementos editoriais como dicas, notas e exceções nas diretrizes de API RESTful. Primeiro, revise os exemplos fornecidos (por exemplo, #101, #116, #104, #114) para ver as inconsistências atuais. Em seguida, leia os comentários para obter sugestões da comunidade sobre um conjunto mínimo de elementos e um formato uniforme. O trabalho envolve editar vários arquivos Markdown, cada um correspondendo a uma regra da diretriz. Identifique todas as instâncias desses elementos e proponha uma convenção de nomenclatura consistente (por exemplo, "Nota:", "Aviso:", etc.) e layout visual. Nenhuma alteração de código é necessária; concentre se no texto e na formatação. A estrutura do repositório pode ser explorada no diretório ` guidelines`.
Pilha de tecnologia
None
Domain
documentation
Tipo Issue
Documentação
DifficultyDificuldade de implementação estimada para um novo contribuidor, de 1 para alterações muito pequenas a 5 para trabalho de nível especializado.
2
Tempo estimadoUm intervalo de tempo aproximado para um colaborador experiente investigar, implementar, testar e preparar um pull request.
Menos de 1 hora
Status da atividadeQuão disponível o issue aparece agora: novo, ativo, obsoleto, bloqueado ou aguardando entrada do mantenedor.
Ativo
ClarityCom que clareza o issue explica a mudança esperada, os critérios de aceitação e a próxima etapa.
Claro
Prerequisites
None
Simpatia para novatosUma pontuação de 1 a 100 que estima o quão acessível este issue é para colaboradores iniciantes.
85