We’ve been working on a better way to display code examples in both Juju documentation, and across all our documentation on the web.
We’d love to get some feedback from the community on this new user interface component before we move to the visual design phase. Just drop us a reply below, we’re always interested in hearing from you.
What problems are we trying to solve?
At the moment, we simply style code blocks in a monospace typeface - and the appearance can be inconsistent across our multiple sites and products.
The main issues we want to resolve are;
There’s no way to clearly show the command output as distinct from the command-line snippet
There’s no way to show multiple versions of the same snippet (for example for different software versions or platforms)
Help text can’t be added to explain what the command means
The copy control is inconsistent across sites and products
In the new design, the documentation writer can offer;
Multiple versions of code snippets
Example output to further guide the user
Descriptive help text
Having copy-to-clipboard is a simple convenience control, but it can also reduce errors where commands are mis-typed or mis-copied.
This new design is modular, and each part; description, version switcher and output panel - can all be shown or hidden depending on the context and the features the author needs.
The next steps for us are to style the controls with the Vanilla framework, produce a working prototype and then test with users so we can learn what works and what doesn’t - and how we can enhance the experience of using code snippets across our docs.
If you’re interested in taking part in user interviews to help improve our products and services (including changes like this), the Canonical User Interview Group is open for willing test subjects volunteers!
My first thought is that having two completely separate boxes for the example command line input and output is not enough for command walk-throughs. Something like this could be very useful, done with Prism.js:
In that example you can see the prompts *and the output for each command in between the prompts. When you click the copy button ( only shown when hovering so not visible in that screenshot ) it actually only copies the text you need to paste into your commandline.
@zicklag That’s awesome, thanks. We did have some discussion around multiple command walk-throughs and we’ll tackle that in a future iteration. I was reluctant to ‘bake in’ the $ sign, as we have to think of other platforms (such as Windows > prompt, but it could be optionally switched with the version too. Thanks for the reply.
The $ is actually completely configurable with Prism.js. You can make it whatever you want. For your setup you could make it customized according to the platform that you selected, maybe.
Folks, there is only one use case that matters, which is standard copy and paste.
A button off to the side is not standard copy and paste.
Anybody who is using a CLI will know how to do standard copy and paste.
The more bells, whistles and complications we add, the less likely it is that our readers can just select the text they want, and do what they normally do, which is some variation of ctrl-c ctrl-v, depending on platform.
Over-engineering this has backfired in the past. Please don’t repeat the mistake of trying to reinvent the wheel so intently that we make the obvious, normal behaviours difficult.
This mistake in the past led to our docs looking weirder than they needed to, with all sorts of extra boxes and buttons that are just not needed. Less really is more. Just get the selection part right, so that the decoration ($ prompts etc) don’t get selected, and let developers do what their muscle memory is already programmed to do.
I totally agree. That is another nice thing about the Prism.js code blocks with the $ prefix. Having the terminal prompt can be important/helpful, depending on the context, to understanding the example and sometimes people will therefore just put the $ prompt in the text, which actually breaks copy and paste or makes it more annoying because you have to leave out the dollar sign. Prism.js makes sure you don’t copy the prompt.
You can use the button, or just highlight it like normal.
