Issue#390 - bold commands in codeblocks #413

jherrman · 2023-10-02T17:03:46Z

Update draft for #390

bergerhoffer

Thanks for submitting this PR! Added some initial feedback.

bergerhoffer · 2023-10-02T18:28:42Z

supplementary_style_guide/style_guidelines/formatting.adoc

@@ -104,6 +104,42 @@ Write all titles and headings, including the titles of product documentation gui
 * _Configuring the node port service range_
 * _How to perform an unsupported conversion from a RHEL-derived Linux distribution to RHEL_

+[[commands-in-code-blocks]]
+== Commands in code blocks


Can you move this up so that it is alphabetical? (Should be first in the file, before "Date formats")

I've also gone back and forth on whether this makes the most sense under formatting, or whether it would be better suited under "Technical examples". It is formatting, but I'm leaning toward the technical examples sense, just so that all of the code block misc is together. wdyt?

+1 For Technical examples

Hm, I'd say it fits rather well under the "Formatting" section, since "Technical examples" primarily seems to deal with guidelines for the content itself rather than its markup.

Also, the "User-replaced values" parts, which deal with a very much related topic, including code block content (which is why I initially bunched up the new section with them), are under Formatting as well.

bergerhoffer · 2023-10-02T18:34:53Z

supplementary_style_guide/style_guidelines/formatting.adoc

+[[commands-in-code-blocks]]
+== Commands in code blocks
+
+As a default, use bold formatting for commands in code blocks, to visually distinguish them from their lead-in sentences and example outputs.


I know this sentence implies it, but I would add another sentence that states that output should not use bold formatting.

bergerhoffer · 2023-10-02T18:39:35Z

supplementary_style_guide/style_guidelines/formatting.adoc

+----
+====
+
+Disregard this guideline for example when the command is not an important part of what you want to show in the given code block.


I get what we're trying to say with this line, but I think this leaves a lot of room for people to ignore this guideline. Maybe we could leave it out?

Or maybe word it differently to state that if you are using bold to emphasize a different item in the code block, you are not required to bold the command?

Well, I do want to leave people some room to manoeuvre around this if they feel so inclined. Your suggestion for the wording does make sense, though.

bergerhoffer · 2023-10-02T18:42:10Z

supplementary_style_guide/style_guidelines/formatting.adoc

@@ -104,6 +104,42 @@ Write all titles and headings, including the titles of product documentation gui
 * _Configuring the node port service range_
 * _How to perform an unsupported conversion from a RHEL-derived Linux distribution to RHEL_

+[[commands-in-code-blocks]]


I know we also briefly talked about stating to show a single command in a code block. And that if you have multiple commands, they should be broken into separate code blocks.

Should we consider adding an entry for this as well? Not sure if it would make sense to add into this one, or to separate them into different entries?

You're right, that's a topic that falls quite squarely under "Commands in code blocks]", so I'll add a mention of that, too.

bergerhoffer · 2023-10-02T18:42:36Z

supplementary_style_guide/style_guidelines/formatting.adoc

+== Commands in code blocks
+
+As a default, use bold formatting for commands in code blocks, to visually distinguish them from their lead-in sentences and example outputs.
+


Do you think we need to clarify that you should still use bold even if there is no example output?

I think so, good point.

bergerhoffer · 2023-10-02T18:43:17Z

supplementary_style_guide/style_guidelines/formatting.adoc

+
+.Example AsciiDoc: Command and its output in a code block
+
+  Verify that the `libvirt` default network is active and configured to start automatically:


Maybe show this as a step, since that's how it would normally appear in a procedure? (If you do, update in the below rendered output as well

Suggested change

Verify that the `libvirt` default network is active and configured to start automatically:

. Verify that the `libvirt` default network is active and configured to start automatically:

Actually, I just tested this and it seems to break the formatting of the example in the render for some reason. So, given that it's not really important for the example lead-in sentence to be a step, I'd leave it out.

dfitzmau · 2023-10-03T08:24:44Z

supplementary_style_guide/style_guidelines/formatting.adoc

@@ -104,6 +104,42 @@ Write all titles and headings, including the titles of product documentation gui
 * _Configuring the node port service range_
 * _How to perform an unsupported conversion from a RHEL-derived Linux distribution to RHEL_

+[[commands-in-code-blocks]]
+== Commands in code blocks


+1 For Technical examples

dfitzmau · 2023-10-03T08:28:27Z

supplementary_style_guide/style_guidelines/formatting.adoc

+  ----
+
+
+This renders as:


Incomplete sentence. How about: The previous AsciiDoc example outputs as follows?

I'm suggesting this in the event that a new writer scans the RH SSG (to validate term usability) to check for instances of "This renders as" and they then apply it to customer docs.

This exact wording was actually used in multiple other examples in the section, and I just copied it as a "template". Doesn't change the fact that it's an incomplete sentence, so I'll update the other occurrences, too.

dfitzmau · 2023-10-03T08:32:27Z

supplementary_style_guide/style_guidelines/formatting.adoc

+
+Disregard this guideline for example when the command is not an important part of what you want to show in the given code block.
+
+In addition, both in commands and outputs in code blocks, observe the correct mark-up for user-replaced values, as described in xref:user-replaced-values[] and xref:user-replaced-values-xml[].


The three "in" instances makes me stop and reread the sentence. How about:

For a command and its output in a code block, observe the correct mark-up for user-replaced values, as described in xref:user-replaced-values[] and xref:user-replaced-values-xml[].

supplementary_style_guide/style_guidelines/formatting.adoc

Kudos to Andrea Hoffer and Darragh Fitzmaurice for the feedback

jherrman · 2023-10-03T18:51:15Z

@bergerhoffer @dfitzmau thank you for the reviews, hopefully the next iteration is a bit ship-shape-er :-)

Diff: f0ddde1

mportman12

Left some suggestions.

supplementary_style_guide/style_guidelines/formatting.adoc

Kudos to Miriam Portman for the suggestion Co-authored-by: Miriam Portman <[email protected]>

jherrman · 2023-10-13T13:09:01Z

Thank you for the reviews @bergerhoffer @dfitzmau @mportman12 ! Your suggested changes have now been applied, feel free to take another look at the diff and merge the PR if everything looks copacetic.

bredamc

@jherrman Some minor comments for your consideration :)

supplementary_style_guide/style_guidelines/formatting.adoc

bredamc · 2023-11-06T11:58:08Z

supplementary_style_guide/style_guidelines/formatting.adoc

+----
+====
+
+Do not use bold formatting for the output, unless you need to highlight a specific part of it. When you do emphasize a non-command item in a code block, you are not required to bold the command.


Suggested change

Do not use bold formatting for the output, unless you need to highlight a specific part of it. When you do emphasize a non-command item in a code block, you are not required to bold the command.

Do not use bold formatting in the command output. If you need to highlight a specific part of the output, use a different highlighting method.

I don't think this is good guidance. Writers should still be able to use bolded strings in outputs if necessary, especially if in the given code block, the output is more important than the command itself. Also, it would be rather strange to express the same kind of emphasis differently in the very same code block.

Your other suggestions are decidedly improvements, though, thank you :-)

@jherrman Apologies for the delay in replying to your comment. It seems odd to me to say bold the command in one place and not in another, but perhaps I misunderstood the intent of this update.

Well, the idea is basically "bold the important part, so that it's visually distinct" - and since the command itself is usually the important part of a CLI example (and the given step in general), it would be the default part do bold. However, when a part of the output is as important as the command in the given context, or more, we should not bar the writer from bolding something else than the command, and potentially even leaving the command un-bolded.

It's entirely possible I did not formulate that clearly enough in the actual source update, though...

@jafiala Can you give us an example of what you're thinking of with bolding pieces of the output?

Thanks for the examples, @jherrman.

I think it's better to highlight such lines in the command output by using a callout instead of bold text? The following example shows callouts (in a code example, but the same method could be used for command output):
https://docs.openshift.com/pipelines/1.13/about/understanding-openshift-pipelines.html

WDYT?

Honestly, callouts do not seem like an optimal solution to me.

They are pretty wonky to work with in adoc (for instance can only be at the end of a line, cannot be used out of sequence, one callout cannot be used repeatedly, and they must always have an explanation under the codeblock, AFAIK). Also, Customer Portal stylesheets do not render them very well, currently.

When they work as expected, callouts are visually very distinct, which may not always be what you want when highlighting a small part of a command output.

If the general intention behind this update is "bold out the operative/important parts of the code block for greater visual clarity", I would say the output should follow that consistently with the commands. Also, it's easier for writers to internalize and follow.

@jherrman and @dfitzmau Thank you both! I understand that callouts might not be optimal, but I wonder if we could highlight the command output in some other way rather than by reusing the bold format.

Do you know whether the highlight syntax described here would render correctly in Customer Portal and OpenShift docs?

I tried that syntax a few years ago on the CP and it did render, but I was informed to drop it as the yellow highlighting was really distracting. It definetly grabs attention, but it distracts from the surrounding content. I can understand why yellow is a well-adopted colour for safety 💛

I tested out the #highlight# markup earlier today. Renders reasonably well in asciidoctor (though, as Darragh points out, the colour is a bit much), but both bccutil and the Customer Portal stylesheets completely ignore it, unfortunately:

https://dxp-docp-prod.apps.ext-waf.spoke.prod.us-west-2.aws.paas.redhat.com/documentation/en-us/zen_and_zany_asciidoc_training_titles/42/html-single/davozenis_advanced_asciidoc_training/index?lb_target=stage#proc_test-two_assembly_nested-test

Source: https://privatebin.corp.redhat.com/?d7d35e248ea634d9#6icGw5GgEyf71smCmNSsPem7bvZ6CFMBjiLVkA7zi8Uj

supplementary_style_guide/style_guidelines/formatting.adoc

Co-authored-by: Breda McColgan <[email protected]>

jherrman · 2024-01-26T13:57:33Z

Hi @mportman12 , I think you need to ack the changes (based on your comments from Oct 11) before the PR can be merged.

Cheers,
J.

mportman12 · 2024-01-26T14:07:59Z

@jherrman I think you need ACK from Breda, not me. All my comments have been resolved.

mportman12

LGTM

jherrman · 2024-01-26T14:25:52Z

@bergerhoffer @dfitzmau (or anyone else with merging privileges), unless you have any other comments or suggestions as to the changes, please consider merging this sooner rather than later - so that this PR and #390 don't bloat their respective queues unnecessarily.

Thanks!
J.

dfitzmau · 2024-01-26T14:28:00Z

@bergerhoffer @dfitzmau (or anyone else with merging privileges), unless you have any other comments or suggestions as to the changes, please consider merging this sooner rather than later - so that this PR and #390 don't bloat their respective queues unnecessarily.

Thanks! J.

Hi @jherrman . Looks like Andrea is on PTO. I can merge this PR when the 3rd approval tick is provided.

jherrman · 2024-01-29T12:37:01Z

@dfitzmau I see, thank you for the clarification.

@bredamc , unless there are any further improvements that you'd like to see in this PR, could you provide an approval tick, so it can be merged?

Thanks, and have an excellent day!
J.

bredamc · 2024-01-31T09:35:46Z

@jherrman Would you mind adding it to the agenda for the SSG meeting today, just to make sure all agree with the proposed change?

jherrman · 2024-01-31T09:42:21Z

@jherrman Would you mind adding it to the agenda for the SSG meeting today, just to make sure all agree with the proposed change?

I won't be able to attend the style guide meeting today due to a QPS meeting, but if that's not an issue, I can definitely pop this on the agenda for discussion. Alternatively, I'd leave it until the next meet-up.

bredamc · 2024-01-31T09:55:11Z

I can attend the first 30 minutes of today's meeting if that helps, but I'm happy to wait until you can attend if you prefer? I know you'd like to get this PR merged sooner rather than later, but I am uncomfortable with the text in line 43, as indicated by my comment above, and would like to get the council's opinion.

jherrman · 2024-01-31T10:14:46Z

@bredamc , sounds like a plan :-) I added the issue as the first one to be discussed at today's style meet-up.

bredamc · 2024-01-31T13:13:55Z

@jherrman Could you please provide an example of where the proposed formatting would be preferred over a different highlighting method?

jherrman · 2024-01-31T20:42:03Z

@jherrman Could you please provide an example of where the proposed formatting would be preferred over a different highlighting method?

Added some examples to the thread above

dfitzmau · 2024-02-01T09:12:59Z

@jherrman Could you please provide an example of where the proposed formatting would be preferred over a different highlighting method?

Added some examples to the thread above

On OpenShift, we have a rule of one command per codeblock and the output should also be in its own codeblock. In saying this, I do see some edge cases in OCP docs where bolding some aspects of a large output block would help a customer see what key output lines they need to see to verify a command ran succesfully. The non-essential output would still hold value in that it provides a customer comfort that this output is also expected.

As in a previous comment, callouts could be used, but callouts used with ifdef or ifndef statements can create a held-with-sticky-tape file, as I've found out recently.

jherrman · 2024-02-01T10:25:23Z

On OpenShift, we have a rule of one command per codeblock and the output should also be in its own codeblock.

If I remember correctly, the stylesheets on https://docs.openshift.com automatically bold out everything in a code block (though probably in different typefaces based on the context). That way, keeping the command and the output together would create a long(ish) block of bolded text, which is not great for visual clarity either - so keeping them separate is very sensible. However, it also seems to create some "textbox bloat", which is something we generally try to avoid when possible. Therefore, given that Customer Portal stylesheets do not use bold typeface automatically, keeping the comand and the output together makes more sense in CP-based docs.

This, nevertheless, raises a good question: Given that the RH SSG does not aim to govern only documentation that resides on the Customer Portal, how much do we want to be prescriptive about matters that may be governed by the stylesheets of the respective documentation site, and thus outside the writer's control?

As in a previous comment, callouts could be used, but callouts used with ifdef or ifndef statements can create a held-with-sticky-tape file, as I've found out recently.

Yeah, callouts do not work super-great in asciidoc in general, in my experience, and unless they are eminently useful in the given context, I usually prefer to avoid them.

jherrman · 2024-02-13T16:57:50Z

Based on the discussion on Slack , I've updated the guidelines about bolding in command output - 9346e54

@dfitzmau @bergerhoffer @bredamc , please take a look and either approve the PR or let me know if any other changes are needed.

Cheers,
J.

bredamc

LGTM! Thank you for your patience, @jherrman :)

bergerhoffer

LGTM

bergerhoffer · 2024-02-20T17:36:31Z

supplementary_style_guide/style_guidelines/formatting.adoc

+
+.Example AsciiDoc: A command and its output in a code block
+
+  Verify that the `libvirt` default network is active and configured to start automatically:


My only feedback is whether this example should actually be shown as a bullet or numbered step. But I don't think that's important enough to hold up the PR over since it has 2 other approvals. Just something to consider if we should adjust in a separate PR or not!

bergerhoffer · 2024-02-20T17:37:40Z

3 approvals, merging!

jherrman added 2 commits October 2, 2023 18:19

Added a section on bolded commands in codeblocks

8ce04c0

Bolded out other commands in codeblocks, for consistency

5e81685

jherrman mentioned this pull request Oct 2, 2023

Establish clearer guidelines for command highlighting in code blocks #390

Closed

bergerhoffer reviewed Oct 2, 2023

View reviewed changes

bergerhoffer added the Style guideline Topics that add or modify style guidelines label Oct 2, 2023

dfitzmau reviewed Oct 3, 2023

View reviewed changes

Applied changes based on review

f0ddde1

Kudos to Andrea Hoffer and Darragh Fitzmaurice for the feedback

mportman12 requested changes Oct 11, 2023

View reviewed changes

supplementary_style_guide/style_guidelines/formatting.adoc Outdated Show resolved Hide resolved

supplementary_style_guide/style_guidelines/formatting.adoc Outdated Show resolved Hide resolved

supplementary_style_guide/style_guidelines/formatting.adoc Outdated Show resolved Hide resolved

jherrman and others added 3 commits October 13, 2023 15:02

Updating supplementary_style_guide/style_guidelines/formatting.adoc

f7d7cbd

Kudos to Miriam Portman for the suggestion Co-authored-by: Miriam Portman <[email protected]>

Update supplementary_style_guide/style_guidelines/formatting.adoc

358e3d7

Kudos to Miriam Portman for the suggestion Co-authored-by: Miriam Portman <[email protected]>

Update supplementary_style_guide/style_guidelines/formatting.adoc

8095c71

Kudos to Miriam Portman for the suggestion Co-authored-by: Miriam Portman <[email protected]>

bredamc reviewed Nov 6, 2023

View reviewed changes

jherrman and others added 3 commits November 6, 2023 14:13

Update supplementary_style_guide/style_guidelines/formatting.adoc

9c97313

Co-authored-by: Breda McColgan <[email protected]>

Update supplementary_style_guide/style_guidelines/formatting.adoc

31ead15

Co-authored-by: Breda McColgan <[email protected]>

Update supplementary_style_guide/style_guidelines/formatting.adoc

ef1efcd

Co-authored-by: Breda McColgan <[email protected]>

dfitzmau previously approved these changes Jan 3, 2024

View reviewed changes

jherrman requested a review from mportman12 January 26, 2024 13:52

mportman12 previously approved these changes Jan 26, 2024

View reviewed changes

Changed phrasing on bolding in output

9346e54

jherrman dismissed stale reviews from mportman12 and dfitzmau via 9346e54 February 13, 2024 16:54

Removed guidelines for output

a05bcc0

bredamc approved these changes Feb 14, 2024

View reviewed changes

dfitzmau approved these changes Feb 15, 2024

View reviewed changes

bergerhoffer approved these changes Feb 20, 2024

View reviewed changes

bergerhoffer merged commit a225f27 into redhat-documentation:main Feb 20, 2024
1 check passed

		== Commands in code blocks

		As a default, use bold formatting for commands in code blocks, to visually distinguish them from their lead-in sentences and example outputs.


		.Example AsciiDoc: Command and its output in a code block

		Verify that the `libvirt` default network is active and configured to start automatically:

	Verify that the `libvirt` default network is active and configured to start automatically:
	. Verify that the `libvirt` default network is active and configured to start automatically:


		Disregard this guideline for example when the command is not an important part of what you want to show in the given code block.

		In addition, both in commands and outputs in code blocks, observe the correct mark-up for user-replaced values, as described in xref:user-replaced-values[] and xref:user-replaced-values-xml[].

	Do not use bold formatting for the output, unless you need to highlight a specific part of it. When you do emphasize a non-command item in a code block, you are not required to bold the command.
	Do not use bold formatting in the command output. If you need to highlight a specific part of the output, use a different highlighting method.


		.Example AsciiDoc: A command and its output in a code block

		Verify that the `libvirt` default network is active and configured to start automatically:

Issue#390 - bold commands in codeblocks #413

Issue#390 - bold commands in codeblocks #413

Conversation

jherrman commented Oct 2, 2023

bergerhoffer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jherrman commented Oct 3, 2023

mportman12 left a comment

Choose a reason for hiding this comment

jherrman commented Oct 13, 2023

bredamc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jherrman Feb 1, 2024 • edited Loading

Choose a reason for hiding this comment

jherrman commented Jan 26, 2024

mportman12 commented Jan 26, 2024

mportman12 left a comment

Choose a reason for hiding this comment

jherrman commented Jan 26, 2024

dfitzmau commented Jan 26, 2024

jherrman commented Jan 29, 2024

bredamc commented Jan 31, 2024

jherrman commented Jan 31, 2024

bredamc commented Jan 31, 2024

jherrman commented Jan 31, 2024

bredamc commented Jan 31, 2024

jherrman commented Jan 31, 2024

dfitzmau commented Feb 1, 2024 • edited Loading

jherrman commented Feb 1, 2024 • edited Loading

jherrman commented Feb 13, 2024

bredamc left a comment

Choose a reason for hiding this comment

bergerhoffer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bergerhoffer commented Feb 20, 2024

jherrman Feb 1, 2024 •

edited

Loading

dfitzmau commented Feb 1, 2024 •

edited

Loading

jherrman commented Feb 1, 2024 •

edited

Loading