Juju GUI: get your users started with getstarted.md

jeffpihach

jeffpihach

on 31 October 2017

Help your users get started with your solution by providing them the first steps in using your newly deployed bundle or charm. The latest release of the Juju GUI now displays a rendered markdown file to the user after deploying a bundle or charm with a getstarted.md file.

Adding this functionality to your bundle deployments couldn’t be easier. Simply add a getstarted.md file to the root of your bundle archive with valid markdown and it will be rendered after the deployment has started.

The getstarted.md file should include the users next steps, and to help you build the best guide possible. We have outlined a few best practices below.

  • State prerequisites upfront so they don’t start down a path they can’t finish.
  • List the minimum number of steps that they should follow to see the charm working at some level of success. e.g get your users to a web dashboard or a REPL. We suggest using fewer than 10 steps.
  • Give your user links to sensible next steps. Link to external resources, most important first.

Extra points to keep in mind

  • Remember your user is in the GUI.
  • Start instruction with verbs – write in the imperative tense.
  • Write the simplest actions. Concentrate on what they need to do to get started.
  • Use code blocks for CLI commands.
  • Use the format of machines, protocols, and full paths to make reaching the most important endpoints of your application obvious.

Examples of some quickstart.md files

Ubuntu cloud

Ubuntu offers all the training, software infrastructure, tools, services and support you need for your public and private clouds.

Newsletter signup

Select topics you’re interested in

In submitting this form, I confirm that I have read and agree to Canonical’s Privacy Notice and Privacy Policy.

Related posts

Simplifying deployment and management of edge clouds with CPLANE.ai

Title: Simplifying deployment and management of edge clouds Speakers: Matt Akins & Brandon Williams Date/Time: June 13, 12:00PM EST / 5:00PM BST Canonical recently announced a partnership with CPLANE.ai to simplify cloud management.…

Charming Discourse with the reactive framework

Recently the Canonical IS department was asked to deploy the Discourse forum software for a revamp of the Ubuntu Community site at https://community.ubuntu.org. Discourse is a modernization of classic forum/bulletin board software packages…

Monitor your Kubernetes Cluster

This article originally appeared on Kevin Monroe’s blog Keeping an eye on logs and metrics is a necessary evil for cluster admins. The benefits are clear: metrics help you set reasonable performance goals, while log analysis can…