search

redhat-documentation / asciidoc-markup-conventions

How to use AsciiDoc mark-up to properly style elements in Red Hat documentation
https://access.redhat.com/documentation/
17 stars 16 forks source link

Keyboard shortcut example doesn't match IBM Style #30

Open melcorr opened 6 years ago

melcorr commented 6 years ago

IBM style pp 219 and elsewhere outlines how keyboard shortcuts should be handled in documentation.

In the Asciidoc Markup conventions doc, we highlight keyboard shortcuts in another manner.

Why is it necessary to break with IBM here? Is it really necessary to highlight it if IBM doesn't say it should be highlighted? I didn't see any discussion of this on the mailing lists.

Thanks!

rkratky commented 6 years ago

The main reason for using the kbd macro provided by AsciiDoctor is that it makes the mark-up semantic, which is something we should encourage. The actual way the result is rendered is up to the brand applied on the CP or elsewhere.

All of these conventions are the result of a CCS-wide initiative that anyone could have participated in. In addition, the WIP conventions were offered to CCS for comments and critique, and all issues that were flagged as contentious were voted on in a CCS-wide survey.