From 39eaf835d0b64a991ce43c5320220896185608b7 Mon Sep 17 00:00:00 2001
From: Matt Broberg <matt@opensource.com>
Date: Tue, 30 Jun 2020 10:35:15 -0500
Subject: [PATCH] Steps to get podman running

- Remove repetitive notes in podman documentation
- Fix links in the usage document
- Tidy the language and grammar
---
 .../en/docs/drivers/includes/podman_usage.inc | 22 +++++++------
 site/content/en/docs/drivers/podman.md        | 31 ++++++++++++++-----
 2 files changed, 35 insertions(+), 18 deletions(-)

diff --git a/site/content/en/docs/drivers/includes/podman_usage.inc b/site/content/en/docs/drivers/includes/podman_usage.inc
index 22c71a96f8..63940a3c54 100644
--- a/site/content/en/docs/drivers/includes/podman_usage.inc
+++ b/site/content/en/docs/drivers/includes/podman_usage.inc
@@ -1,20 +1,22 @@
-## experimental
+## Experimental
 
-This is an experimental driver. please use it only for experimental reasons.
-for a better kubernetes in container experience, use docker [driver]({{< ref "/docs/drivers/docker/" >}})
-
-## Install Podman
-
-- [Podman](https://podman.io/getting-started/installation.html)
+This is an experimental driver. Please use it only for experimental reasons until it has reached maturity. For a more reliable minikube experience, use a non-experimental driver, like [Docker]({{< ref "/docs/drivers/docker.md" >}}).
 
 ## Usage
 
-Start a cluster using the podman driver:
+It's recommended to run minikube with the podman driver and [CRI-O container runtime](https://https://cri-o.io/): 
 
 ```shell
-minikube start --driver=podman
+minikube start --driver=podman --container-runtime=cri-o
 ```
-To make docker the default driver:
+
+Alternatively, start minikube with the podman driver only: 
+
+```shell
+minikube start --driver=podman 
+```
+
+To make podman the default driver: 
 
 ```shell
 minikube config set driver podman
diff --git a/site/content/en/docs/drivers/podman.md b/site/content/en/docs/drivers/podman.md
index 286429b0ef..e47ebc6b80 100644
--- a/site/content/en/docs/drivers/podman.md
+++ b/site/content/en/docs/drivers/podman.md
@@ -11,21 +11,36 @@ aliases:
 This driver is experimental and in active development. Help wanted!
 {{% /pageinfo %}}
 
-The podman driver is another kubernetes in container driver for minikube. similar to [docker](https://minikube.sigs.k8s.io/docs/drivers/docker/) driver. The podman driver is  experimental, and only supported on Linux and macOS (with a remote podman server).
+The podman driver is an alternative container runtime to the [Docker]({{< ref "/docs/drivers/docker.md >}}) driver.
 
 ## Requirements
 
-- Install [Podman](https://podman.io/getting-started/installation) 
-- amd64 system 
+- Linux or macOS operating systems on amd64 architecture 
+- Install [podman](https://podman.io/getting-started/installation.html)
 
-## Try it with CRI-O container runtime.
-
-```shell
-minikube start --driver=podman --container-runtime=cri-o
-```
 
 {{% readfile file="/docs/drivers/includes/podman_usage.inc" %}}
 
 ## Known Issues
 
 - Podman driver is not supported on non-amd64 architectures such as arm yet. For non-amd64 archs please use [other drivers]({{< ref "/docs/drivers/_index.md" >}}) 
+- Podman requirements passwordless running of sudo. If you run into an error about sudo, do the following: 
+
+```shell
+$ sudo visudo
+```
+Then append the following to the section *at the very bottom* of the file where `username` is your user account.
+
+```shell
+username ALL=(ALL) NOPASSWD: /usr/bin/podman
+```
+
+Be sure this text is *after* `#includedir /etc/sudoers.d`. To confirm it worked, try: 
+
+```shell
+sudo -k -n podman version
+```
+
+## Troubleshooting
+
+- Run `minikube start --alsologtostderr -v=7` to debug errors and crashes