Document when to use white space in code blocks

[daobrien]

Perhaps best illustrated with an example.
Original:

[user@host basic-repo]$ *git log --graph --oneline --all*
* 122b62a (`HEAD -> my-feature`, main) add text files with output and reversed output
* 9606c21 update printed message
_...output omitted..._
[user@host basic-repo]$ *git commit -m 'fix broken test'*
[my-feature 0aaf18b] fix broken test
 1 file changed, 1 insertion(+), 1 deletion(-)
[user@host basic-repo]$ *git log --graph --oneline --all*
* 0aaf18b (`HEAD -> my-feature`) fix broken test
* 122b62a (main) add text files with output and reversed output
* 9606c21 update printed message
_...output omitted..._

This block contains 3 commands, and it's pretty easy to "lose" them among all the output.
If we introduce white space:

[user@host basic-repo]$ *git log --graph --oneline --all*
* 122b62a (`HEAD -> my-feature`, main) add text files with output and reversed output
* 9606c21 update printed message
_...output omitted..._

[user@host basic-repo]$ *git commit -m 'fix broken test'*
[my-feature 0aaf18b] fix broken test
 1 file changed, 1 insertion(+), 1 deletion(-)

[user@host basic-repo]$ *git log --graph --oneline --all*
* 0aaf18b (`HEAD -> my-feature`) fix broken test
* 122b62a (main) add text files with output and reversed output
* 9606c21 update printed message
_...output omitted..._

The plan is not to use white space after every command, but rather in those cases where the code block becomes busy and clarity suffers. This is somewhat subjective, and one comment I've received is that "this is not exactly what it looks like in the output". But, we take liberties with the output already by using ...output omitted... and omitting secondary prompts.

I don't think we need strict guidelines, but I do think we need to provide options with some firm boundaries. E.g., how many commands and how much output is too much in a single code block? IMO this example doesn't contain too many commands; 3 commands, 2 of which are the same, and all aimed at illustrating a single point. There's enough output, however, to make those commands start to blend into one confusing code block. A bit of white space separates them into their independent parts. If instead the commands were quite distinct (e.g., git clone followed by editing a file and then committing), then I'd look at two code blocks.

@rclee33 We talked about this a little while back. WDYT?

[daobrien]

Here's an example where the addition of white space wouldn't achieve much:

4.4. Use git add to stage the new directories, and then commit and push.

[student@workstation aap-config]$ git add .
[student@workstation aap-config]$ git commit -m "Add initial directory structure"
...output omitted...
[student@workstation aap-config]$ git push -u origin prod
...output omitted...

This also contains 3 commands, but there's next to no output and overall it's clear and easy to follow.

[rclee33]

Yes, I agree with everything here! The first example is a really helpful one, because it illustrates some useful guiding principles about when and how to group multiple commands into a single block (not too many, commands should be related, and white space adds value). The second example is also useful because it demonstrates when adding white space between commands doesn't add value.

This all makes sense to me!

[julian-cable]

How about stating: Add one blank line between commands in a code block, except where each command occupies only one or two lines?