Improve visual distinctiveness of code for copying, code for illustration, and command snippets

[lauracowen]

My usability tester (relatively new to Java language) found it confusing that the little Java snippets that happened not to have any coloured syntax highlighting in them look a lot like something that should be entered on the command line; for example:

I propose that we should at least have the snippet box display a shell prompt on snippets that should be entered on the command line (but that shell prompt must not be copyable by the Copy button, and should have enough space between it and the start of the command that people swiping to copy don't accidentally copy it):

In addition, can we consider slightly different look-and-feel for the background of code snippets that are to be displayed for illustrative/explanatory purposes (no copy button) vs snippets that are displayed to be copied (and have the copy button). Just a visual cue that could be really subtle but perceptually noticeable; eg a lighter shade of grey or something.

In sum, we have three (or maybe four - see update below) types of snippets to display:

• Java (or other) code that has a copy button and the user is expected to copy and paste that code into a text editor to be compiled/run.
• Java (or other code) that does not have a copy button and the user is not expected to do anything with it. Its purpose is to highlight parts of previously copied code as part of an explanation of what that code does.
• Commands to be run at a command line/terminal prompt and should have the copy button on them.

I think we need the three to be more visually differentiated.

Update: There might be a good argument for having a fourth differentiated snippet: displaying output from a command or console action etc.

[yeekangc]

There is also the kind of block for console output e.g. test results that we want to show for illustration purpose.

So, 4 categories in total:

• Java (or other) code that has a copy button and the user is expected to copy and paste that code into a text editor to be compiled/run.
• Java (or other code) that does not have a copy button and the user is not expected to do anything with it. Its purpose is to highlight parts of previously copied code as part of an explanation of what that code does.
• Commands to be run at a command line/terminal prompt and should have the copy button on them.
• Console output or blocks for illustration purposes

[lauracowen]

So, after discussing this with Megan yesterday, I took a look at our guides and some other doc sites again to look at how we/they present code snippets (see some examples at the bottom of this comment). There's a lot of variation in whether and how they use code snippets, syntax highlighting, and code Copy buttons. So we just need wend our own way....

I took a look at our guides with regard to Megan's suggestion of just not duplicating parts of the code snippets, and considering what impact that would have on our existing guides and on the visual design requirements in this issue. In short, I think it would work.

Single code snippet without duplication

Taking the REST guide as an example first...

In ‘Creating the JAX-RS resource’ section, the bits that are duplicated probably don’t actually need to be. You can provide the whole class file in a single code snippet and then describe it in the text beneath. You can easily see in the main snippet what is meant when the text beneath the snippet refers to the @Path annotation or @Get annotation.

In the testing section, the same goes for the bits that are duplicated from the Java class. Where it’s referring to bits in the pom.xml, we actually want the user to go take a look in the pom.xml. So the text could just refer them to the line <testServerHttpPort>9080</testServerHttpPort> (in inline <code> tags rather than as a block code snippet) so they can go to the pom.xml file and do a find on the file to see what they’re supposed to be looking at (which I think will be obvious in the context).

The Maven guide is potentially a bit harder because it's about a single XML file and XML is rubbish for being concise. However, even here putting the whole of the XML file in a single code snippet then explaining it beneath (eg each point in a separate paragraph, as appropriate) would be fine, I think.

As well as simplifying the flow/navigation of the guides for readers, I think it would also be simpler for guide authors to understand what they're meant to do in terms of how to present code snippets. So we'll end up with more consistent guides which will also help readers of the guides.

Can we try mocking this up?

It would be useful if someone (@Kubik42 ?) could try doing this to a couple of the guides (maybe the REST and Maven guides?) and then showing us the end result on the development server, maybe? Only change what's absolutely necessary (ie the code snippets and any wording/explanation that refers to the code snippets that really doesn't work any more) so that we can see what's changed easily.

Copy button vs no Copy button

Megan also made the point that it's not a great UX to have the Copy button appearing in some places and not others (which others have also mentioned). I think if we simplified what code snippets we present in the guides, I think this problem mostly goes away in that we can now just have the Copy button on all of the snippets.

That would mean that some snippets would have a Copy button when they aren't intended to be copied but I think that wouldn't matter because it would be more obvious to the reader. For example, I took a read through the Spring RESTful web service guide and, without even doing the steps, I could distinguish which snippets I'd want to copy and for what reason, both commands on the command line and code to go in files.

In Spring's managing transactions guide, they do suppress the Copy button on the terminal output at the end of the guide. But, even then, I'm not sure it'd be that confusing if it were on there.

Again, it would be simpler for guide authors to understand if we just have a Copy button on all code snippets (as we had originally...I know...sorry...).

How does this affect the four categories of code snippets?

(see @yeekangc's list above)

1. Java (or other code) that the user is expected to copy and paste.
   • The code for each file is in one place. There may be occasional exceptions but I think this is a good principle to follow.
   • In-depth explanations of the lines of code go below the snippet and refer to the code by quoting either the first line or some other obvious bit in inline monospace markup.
2. Java (or other code) that the user is not expected to do anything with.
   • The duplicated snippets will no longer exist so this will be simpler anyway. This was the bulk of the problem we were trying to address in this issue.
   • For all other code or command output etc, it should be obvious from the context what to do with it. So having a Copy button now will be less confusing.
3. Commands to be run in a terminal
   • They need a Copy button anyway.
   • I still kind of like the idea of having a shell prompt to make it super-clear but I could be persuaded either way (IBM Cloud do this but others like Kubernetes and Docker don't bother). Especially if it causes problems with multiple commands in a single snippet.
4. Console output or other illustrations.
   • It'll be obvious (more obvious?) now from the context that this is console output and isn't intended to be pasted into a file etc.

Some online docs I took a look at

IBM Cloud docs Kubernetes Spring Spring Docker

[yeekangc]

The one consideration that came to mind if we will have a giant copy-able block of code in the beginning always is if it will make users scroll back-and-forth many times ... especially on mobile devices. This may be the only downside? I know personally I hate to have to scroll back-and-forth unnecessarily. @kinueng, any thoughts?

I would think we can at least mock something up for review and discussion. @evelinec @Kubik42, please consider and let us queue this up.

[Kubik42]

There is another case to consider. Some code snippets are not meant to be implemented right at the start of the guide (ex. MicroProfile guide). The user creates the so-to-say skeleton of a class, then writes some files, and then returns to this skeleton and implements it using the files they've written.

Perhaps we could distinguish the blocks that should be copied somehow? Like a different color or some kind of border? Ex. hovering over the blocks changes its color:

Also, one more thing I wanted to ask: is there a way for us to control whats being copied? I'd be great if we could tie multiple commands together like so:

mkdir test
mv test dog

gives you mkdir test && mv test dog

Also, the reason for missing highlighting in the REST guide is because source-highlighter was not defined.

edit: Actually, some of the highlighting is there, but its much less than the rendered doc. Maybe they are missing proper styles on the OL website?

(can you believe I made that gif btw, amazing 💯 )

[Kubik42]

Another idea: have code snippets temporarily light up (for a second or so). Ex. copyable blocks will light up in green with big text over the whole block saying "COPY". Example blocks can light up in red and display text "EXAMPLE". Or something like that.

In any case, we can use the role attribute to add additional classes to each rendered html section. We can then style these classes directly:

// All code blocks that don't have the no_copy class
var copyableSnippets = document.querySelectorAll('.listingblock:not(.no_copy)');
Array.from(copyableSnippets, snpt => {
    snpt.addEventListener('mouseover', function(event) {
        // styling here
    });
});

though jquery would probably work best since it has animate() and fadeIn/fadeOut

[lauracowen]

Regarding @yeekangc's point about scrolling up and down - that may not be a major problem because fewer code snippets will make it easier to know where you are. Maybe. Something we can take a look at in a mockup though.

Regarding the case @Kubik42 mentions above (about creating a skeleton then returning to it). I did wonder about that case. One thing I thought was whether that's just a case of how we structure the guide. For example, if it's a case of creating just a skeleton, is that step even necessary or is it more appropriate to be in the start directory as a skeleton? (it may not be - it might be that there's learning to be done from just creating the skeleton - I just want to make sure we're questioning this more holistically than just trying to fix the low-level problem) Do you have some good examples of where this might or might not work in our current guides?

[Kubik42]

Actually the only guide that uses a skeleton class is the microprofile intro guide. The user initially creates a skeleton of a class, then like you said does some learning and creates additional classes, they then return to the skeleton class and implement it.

Any thoughts on the highlighting I talked about?

[lauracowen]

@Kubik42 The lighting up, you mean? I'm not sure about that. I think it'll be overkill for most people - developers generally understand that a code snippet is there to be copied at the point when they see it. That's a fairly normal convention. There's a risk that flashing stuff will make it look like xmas tree. Also, it relies on the reader spotting it at the right time.

You're welcome to mock it up (separately from the other) if you want to see what it looks like but I think it's probably not necessary to go so far with the cues. :)

[Kubik42]

Ok that makes sense. It will probably be too flashy.

[lauracowen]

Example (for info) of how Twilio present their code snippets: https://www.twilio.com/docs/guides/how-to-receive-and-reply-in-java#generating-twiml-in-your-web-application

[Kubik42]

hmm, that would be really cool, eliminating the need to scroll up and down. But it limits the space for the actual guide and makes everything look really cramped. Perhaps it would work to have clickable code snippets, which pop over to the left side of the page when clicked. But this would only look good in full screen, otherwise the code snippet will be too small. Plus, it probably wont work on phones and tablets due to small screens.

[evelinec]

@Kubik42 any more work on this issue?

[Kubik42]

I think we can close this since the design team is working on a new layout that addresses these concerns. @lauracowen what do you think?

[lauracowen]

Yes, I think we're handling this elsewhere. Maybe put a link in this issue to the one for the new guide designs?

[cajaygle]

The guide redesign issue: https://github.com/OpenLiberty/openliberty.io/issues/145

@megmulsy please re-read through this issue to make sure all items have been addressed.

[salmad3]

Redesign issue has previously been addressed.