combine user guides, rephrase

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>

site/content/docs/developer-guide/custom-indexes.md

@@ -1,25 +1,37 @@
 ---
-title: Custom Indexes
+title: Hosting Custom Plugin Indexes
 slug: custom-indexes
 weight: 500
 ---
 
-Custom indexes allow you to distribute your own custom plugins without having to
-go through `krew-index`. Hosting your own custom index is as simple as creating
-a git repository with the following structure:
+[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 kubectl plugins).
+
+Hosting your own custom index is as simple as creating a git repository with the
+following structure:
+
 ```text
-custom-index/
-  - plugins/
-    - bar.yaml
-    - ...
+.
+└── plugins/
+    ├── plugin-a.yaml
+    ├── plugin-b.yaml
+    └── 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 through git.
+- 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 ones in
-`krew-index`. Users of your index will need to install your plugin using the
-explicit `<INDEX>/<PLUGIN>` syntax.
+Your custom index can contain plugins that have the same name as the ones in
+`krew-index`.
+
+Users of your index will need to install your plugin using the
+explicit `<INDEX>/<PLUGIN>` syntax. See the [user guide][ug].
+
+[ug]: {{< relref "../user-guide/using-custom-indexes.md">}}

site/content/docs/user-guide/using-custom-indexes.md

@@ -0,0 +1,83 @@
+---
+title: Using Custom Plugin Indexes
+slug: custom-indexes
+weight: 800
+---
+
+Plugin indexes contain plugin manifests, which are documents that describe
+installation procedure for a plugin. For discovery purposes, Krew comes with a
+`default` plugin index,  plugins hosted in the [`krew-index`
+repository](https://github.com/kubernetes-sigs/krew-index).
+
+However, some plugin authors may choose to host their own indexes that contain
+their curation of kubectl plugins. These are called "custom plugin indexes".
+
+## Adding a custom index
+
+A custom plugin index can be added with the `kubectl krew index add` command:
+
+```sh
+{{<prompt>}}kubectl krew index add foo https://github.com/foo/custom-index.git
+```
+
+The URI you use can be any [git remote](https://git-scm.com/docs/git-remote)
+(e.g., `git@github.com:foo/custom-index.git`).
+
+## Removing a custom index
+
+You can remove a custom plugin index by passing the name it was added with to
+the remove command:
+
+```sh
+{{<prompt>}}kubectl krew index remove foo
+```
+
+## Listing indexes
+
+To see what indexes you have added you can run the list command
+
+```sh
+{{<prompt>}}kubectl krew index list
+{{<output>}}INDEX    URL
+default  https://github.com/kubernetes-sigs/krew-index.git
+foo      https://github.com/foo/custom-index.git{{</output>}}
+```
+
+## Installing plugins from custom indexes
+
+Commands for managing plugins (e.g. `install`, `upgrade`) work with custom
+indexes as well.
+
+By default, Krew prefixes plugins with a `default/` prefix. However, if you have
+a plugin installed from a custom index, you need to specify it in format
+`INDEX_NAME/PLUGIN_NAME`.
+
+For example, to install a plugin named `bar` from custom index `foo`:
+
+```sh
+{{<prompt>}}kubectl krew install foo/bar
+```
+
+Similarly:
+
+- To list all plugins (including the ones from custom indexes), run:
+
+    ```sh
+    {{<prompt>}}kubectl krew search
+    ```
+
+- 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
+
+    ```sh
+    {{<prompt>}}kubectl krew info INDEX_NAME/PLUGIN_NAME
+    ```
+
+
+> **Caveat:** If two indexes offer a plugin with the same name, only one can
+> be installed at any time.