zalando/restful-api-guidelines

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

Open

#660 创建于 2021年5月18日

在 GitHub 查看
 (11 评论) (0 反应) (1 负责人)CSS (1,984 star) (356 fork)batch import
editorialenhancementhelp wanted

描述

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:

贡献者指南

技术栈
无
领域
documentationcontent
议题类型
documentation
难度面向新贡献者的预计实现难度，1 表示很小改动，5 表示专家级工作。
2
预计时间有经验贡献者完成调查、实现、测试并准备 pull request 的粗略时间范围。
1-2 days
活动状态议题当前的可参与程度：新鲜、活跃、陈旧、阻塞或等待维护者输入。
stale
清晰度议题是否清楚说明期望改动、验收标准和下一步。
mostly clear
前置要求
Familiarity with RESTful API guidelinesKnowledge of Markdown
新手友好度1-100 的估计分数，表示该议题对首次贡献者的友好程度。
45
研究方向
The issue aims to standardize the layout and naming of editorial elements like hints, notes, and exceptions across the RESTful API guidelines. First, review the provided examples (e.g., #101, #116, #104, #114) to see current inconsistencies. Then, read through the comments for community suggestions on a minimal set of elements and uniform format. The work involves editing multiple Markdown files, each corresponding to a guideline rule. Identify all instances of these elements and propose a consistent naming convention (e.g., 'Note:', 'Warning:', etc.) and visual layout. No code changes are needed; focus on text and formatting. The repository's structure can be explored in the ` guidelines` directory.
Editorial: Uniform Layout and Naming of Hints, Remarks, Exceptions etc. · zalando/restful-api-guidelines#660 | Good First Issue