the tech-doc puzzle of UI-markup

the case

  • in technical docs, its known when to use the code font, this but what about the markup of other UI elements?
  • neither code snippets nor another computer-terminology
    • for example, how to document names of menus in navigation?

solution

  • seems like WYSIWYGs do use tags incorrectly
    • <em> instead of <i>
    • <strong> instead of <b>
  • but it flies ! two logical conclusions
    • either it’s only temporal and the tool start breaking apart in a while and it’s bad
    • or the highly granular nitty-gritty of HTML specs are error-prone and it’s good
  • this actually is an old debate
  • natural language is defined by its usage and HTML is semi-natural so to see that headings or other semantic markup is used as a typographic convention or different semantic meaning and it works is enough and
  • let life (evolution) decide

findings

  • we are using <em> wrong — intended for stress emphasis, i.e. where upon speaking the term in a different phonetic level you’d change the meaning of the sentence
  • we are using <strong> wrong —intended for emphasis, i.e. you elevate the meaning of the word without phonetic dimension, the word it’s simply important (warning! danger!)
  • we should use <b> and <code> mostly— <b> has a meaning notice me fast.It’s not that important, but it should stand out for any other reason (fast reading)
  • don’t use quotation marks using <code>
  • for a technical term that is not in code font, use <i>— for example really technical terminology or even inline error messages. For block-level error messages, I’d recommend <blockquote>, eh ?

sources

Leave a Reply

Your email address will not be published. Required fields are marked *