From 2d995f74c4db6561b69338037cde302094a4e40e Mon Sep 17 00:00:00 2001
From: Ahmet Alp Balkan <ahmetb@google.com>
Date: Tue, 30 Jun 2020 21:16:26 -0700
Subject: [PATCH] Extend the developer guide

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>
---
 .../docs/developer-guide/custom-indexes.md    | 41 +++++++++++++------
 .../docs/user-guide/using-custom-indexes.md   |  4 +-
 2 files changed, 30 insertions(+), 15 deletions(-)

diff --git a/site/content/docs/developer-guide/custom-indexes.md b/site/content/docs/developer-guide/custom-indexes.md
index 3a8d31be..467b1b70 100644
--- a/site/content/docs/developer-guide/custom-indexes.md
+++ b/site/content/docs/developer-guide/custom-indexes.md
@@ -4,13 +4,34 @@ slug: custom-indexes
 weight: 500
 ---
 
-[Custom plugin indexes][ug] allow plugin developers to curate and distribute their plugins without
-having to go through the centralized [`krew-index`
-repository](https://github.com/kubernetes-sigs/krew) (which is a
-community-maintained curation of kubectl plugins).
-
-Hosting your own custom index is as simple as creating a git repository with the
-following structure:
+Krew comes with a plugin index named `default` that points to the
+[`krew-index` repository](https://github.com/kubernetes-sigs/krew) which allows
+centralized discovery through community curation.
+
+However, you can host your own plugin indexes (and possibly remove/replace the
+`default` index). It’s not recommended to host your own plugin index, unless you
+have a use case such as:
+
+- your plugin is not accepted to `krew-index`
+- you want to full control over the distribution lifecycle of your own plugin
+- you want to run a private plugin index for your organization
+
+Hosting your own custom index is simple:
+
+- Custom index repositories must be `git` repositories.
+- Your clients should have a read access to the repository (if the repository
+  is not public, users can still authenticate to it with SSH keys or other
+  [gitremote-helpers](https://git-scm.com/docs/gitremote-helpers) installed
+  on the client machine).
+- The repository must contain a `plugins/` directory at the root, with at least
+  one plugin manifest in it. Plugin manifests should be directly in this
+  directory.
+- Ensure plugins manifests are valid YAML and passes Krew manifest validation
+  (optionally, you can use the
+  [validate-krew-manifest](https://github.com/kubernetes-sigs/krew/tree/master/cmd/validate-krew-manifest)
+  tool for static analysis).
+
+Example plugin repository layout:
 
 ```text
 .
@@ -20,12 +41,6 @@ following structure:
     └── plugin-c.yaml
 ```
 
-- Your custom index should contain a `plugins/` directory with at least one plugin
-manifest in it.
-
-- Users will be able to access your custom index through Krew as long as they're
-able to access the repository URL through `git`.
-
 ## Duplicate plugin names
 
 Your custom index can contain plugins that have the same name as the ones in
diff --git a/site/content/docs/user-guide/using-custom-indexes.md b/site/content/docs/user-guide/using-custom-indexes.md
index 59698a0d..c02f2378 100644
--- a/site/content/docs/user-guide/using-custom-indexes.md
+++ b/site/content/docs/user-guide/using-custom-indexes.md
@@ -66,13 +66,13 @@ Similarly:
     {{<prompt>}}kubectl krew search
     ```
 
-- To remove a plugin, you don't need to specify its index
+- To remove a plugin, you don't need to specify its index:
 
     ```sh
     {{<prompt>}}kubectl krew uninstall PLUGIN_NAME
     ```
 
-- To get information about a plugin from a custom index
+- To get information about a plugin from a custom index:
 
     ```sh
     {{<prompt>}}kubectl krew info INDEX_NAME/PLUGIN_NAME