zalando/restful-api-guidelines

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

Open

#660 opened on 2021年5月18日

GitHub で見る
 (11 comments) (0 reactions) (1 assignee)CSS (1,984 stars) (356 forks)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
Issue 種別
documentation
難度新しい貢献者にとっての実装難度です。1 は非常に小さな変更、5 は専門的な作業です。
2
推定時間経験ある貢献者が調査、実装、テスト、pull request 準備にかけるおおよその時間範囲です。
1-2 days
活動状況Issue が今どれだけ取り組みやすいかを示します。新しい、活発、古い、ブロック中、またはメンテナー入力待ちなどです。
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.