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
Wireframe
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! 
Best wishes,
Will & the Canonical Design Team
