Editorial: Uniform Layout and Naming of Hints, Remarks, Exceptions etc.
tfrauenstein opened this issue · comments
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
I propose to use several features provided by Asciidoc for formatting:
- Admonitions for hints, exceptions and etc.
- Sidebars to highlight a block of text.
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)
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 |
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.
@tfrauenstein and @vadeg : please coordinate whether to do this or #674 first, as there will be a lot of conflicts.
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.
@vadeg do you expect you can get to this in the near future?
@ePaul yes. I am testing the UI for asciidoc. Current schema doesn't support properly some formatting components.
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.
@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.