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

[tfrauenstein]

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:

• Hint: https://opensource.zalando.com/restful-api-guidelines/#101
• Example: https://opensource.zalando.com/restful-api-guidelines/#116 https://opensource.zalando.com/restful-api-guidelines/#104 https://opensource.zalando.com/restful-api-guidelines/#114
• Note + Tip: https://opensource.zalando.com/restful-api-guidelines/#114
• Reasoning: https://opensource.zalando.com/restful-api-guidelines/#114

[vadeg]

I propose to use several features provided by Asciidoc for formatting:

1. Admonitions for hints, exceptions and etc.
2. Sidebars to highlight a block of text.

[ePaul]

From the meeting:

• We agree that unifying this is useful
• @vadeg will add a proposal on how to do this (like 3-4 different things)

[vadeg]

I have collected a number of occurrences of different elements and mapped them to possible replacements from AsciiDoctor

Current element	Occurrences	AsciiDoctor Admonition element
Hint	32	TIP or NOTE
Example	10	Implement new EXAMPLE admonition ( An example how to do this. Or keep it as of now )
Note	47	NOTE
TIP	1	TIP
Reasoning	1	NOTE
Exception	7	IMPORTANT
Warning	1	WARNING

[tfrauenstein]

Thx for the progress here -- looks good. Remarks:
a) Let us provide a short definition of when to use TIP vs. NOTE when mapped from Hint
b) The only 1 Warning is more a Note
c) Let us stick to use Exception (create new new admonition) -- it is important for a guideline rule framework.

[ePaul]

@tfrauenstein and @vadeg : please coordinate whether to do this or #674 first, as there will be a lot of conflicts.

[tkrop]

It may also make sense to realign on how to emphasize keywords like MUST, SHOULD, RECOMMENDED, etc. In text we currently use must, should, ... - also often forgetting the bold, while we use MUST, SHOULD, ... in the rule titles. I think we should strive for consistency here too - especially since we refer to RFC2119 in the Conventions Section. See also #693.

[ePaul]

@vadeg do you expect you can get to this in the near future?

[vadeg]

@ePaul yes. I am testing the UI for asciidoc. Current schema doesn't support properly some formatting components.