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.

[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.

[vadeg]

@tfrauenstein

a) Let us provide a short definition of when to use TIP vs. NOTE when mapped from Hint

Do you suggest to provide it somewhere in the document? If you have any guidance what should be the note and what should be the tip I would like to have it before making changes.

[tfrauenstein]

@vadeg I do not yet have a specific guidance, and propose that we should proceed only with 'note'. If it turns out that some hints are better handled as 'note', then we can use it and define the criteria. I would not overload the doc with a definition -- it should be clear from context.

[ePaul]

We agreed that this is still worth doing, but currently nobody has time.
Approach:

1. consistently use the existing annotations where they fit.
2. use the examples from Document how to create a new admonition type asciidoctor/asciidoctor-extensions-lab#9 to implement new annotations for exception + example, then use them.

Volunteers are welcome!