diff --git a/doc.go b/doc.go
index 367f25c728..3d0c435819 100644
--- a/doc.go
+++ b/doc.go
@@ -1,32 +1,70 @@
-// Package image provides libraries and commands to interact with containers images.
+// The package image provides libraries and commands to interact with container images.
 //
 //  package main
 //
 //  import (
-//   	"context"
-//  	"fmt"
+//	"context"
+//	"fmt"
 //
-//  	"github.com/containers/image/v5/docker"
+//	"github.com/containers/image/v5/docker"
 //  )
 //
 //  func main() {
-//  	ref, err := docker.ParseReference("//fedora")
-//  	if err != nil {
-//  		panic(err)
-//  	}
-//  	ctx := context.Background()
-//  	img, err := ref.NewImage(ctx, nil)
-//  	if err != nil {
-//  		panic(err)
-//  	}
-//  	defer img.Close()
-//  	b, _, err := img.Manifest(ctx)
-//  	if err != nil {
-//  		panic(err)
-//  	}
-//  	fmt.Printf("%s", string(b))
+//	ref, err := docker.ParseReference("//fedora")
+//	if err != nil {
+//		panic(err)
+//	}
+//	ctx := context.Background()
+//	img, err := ref.NewImage(ctx, nil)
+//	if err != nil {
+//		panic(err)
+//	}
+//	defer img.Close()
+//	b, _, err := img.Manifest(ctx)
+//	if err != nil {
+//		panic(err)
+//	}
+//	fmt.Printf("%s", string(b))
 //  }
 //
 //
+// ## Notes on running in rootless mode
+//
+// If your application shall run in rootless mode, for instance to be able to
+// read from podman's user storage, then the following additional steps have to
+// be performed at startup of your application:
+//
+//  package main
+//
+//  import (
+//  	"github.com/containers/storage/pkg/reexec"
+//	"github.com/syndtr/gocapability/capability"
+//  )
+//
+//  var neededCapabilities = []capability.Cap{
+//          capability.CAP_CHOWN,
+//          capability.CAP_DAC_OVERRIDE,
+//          capability.CAP_FOWNER,
+//          capability.CAP_FSETID,
+//          capability.CAP_MKNOD,
+//          capability.CAP_SETFCAP,
+//  }
+//
+//  func main() {
+//          	reexec.Init()
+//
+//        	capabilities, err := capability.NewPid(0)
+//		if err != nil {
+//			panic(err)
+// 		}
+//		for _, cap := range neededCapabilities {
+//			if !capabilities.Get(capability.EFFECTIVE, cap) {
+//				// We miss a capability we need, create a user namespaces
+//				unshare.MaybeReexecUsingUserNamespace(true)
+//			}
+//		}
+//  		// rest of your code follows here
+//  }
+//
 // TODO(runcom)
 package image