Style guidance review

[lauracowen]

Two things:

"Update" actions in guides
https://github.com/OpenLiberty/draft-guides-template/wiki/Guidelines-for-Structure-and-Styles#code-command (option 3 "update")

I don't like the way that we have the action boxes with the leaky green line - I'm pretty sure they weren't designed to be used like this, or usability tested like this:

It looks as if the site style sheet has rendered badly and I don't think that's what the intention of the design was for these action arrows.

On occasions when it's necessary to do an "update" action, can't the instruction just come before the arrow?

I'm not sure it's actually necessary to have a specific style for how to present an "update" action because it should be really rare that any guide has an "update" action anyway (only when it makes sense like changing the configuration from one implementation to another, like say moving a Spring Boot app from Tomcat to Open Liberty where that's an actual process that a real person might need to go through). Enabling trace is just something you do as part of your application code, like adding fault tolerance or metrics annotations (you have to recompile your code - it's not like making some external config change) - just assume they're writing the app (ie "create") and they're adding the relevant annotations. It would be a much simpler story.

Mentioning XML elements by name
https://github.com/OpenLiberty/draft-guides-template/wiki/Guidelines-for-Structure-and-Styles#xml-elements
This reads like the style guidance has been changed at some point from not including the triangular brackets to including them - why? Including the XML triangular brackets just clutters up the text. Can we change it back so that elements should just be referred to by name in monospace eg featureManager?

[yeekangc]

@gkwan-ibm

[yeekangc]

If we have guides that are guilty of these, we should have file separate issues to address them if they don't exist already.

[gkwan-ibm]

The guides will remove the triangular brackets by OpenLiberty/guides-common#533

[gkwan-ibm]

The wiki https://github.com/OpenLiberty/draft-guides-template/wiki/Guidelines-for-Structure-and-Styles#xml-elements was updated

[gkwan-ibm]

The first thing is pending on OpenLiberty/openliberty.io#1940