Initial changes to developer guide section of docs (#690)

Author: chriskim06

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

@@ -5,29 +5,29 @@ weight: 500
 ---
 
 Krew comes with a plugin index named `default` that points to the
-[`krew-index` repository](https://github.com/kubernetes-sigs/krew) which allows
+[`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:
+However, you can host your own plugin indexes (and possibly remove or replace the
+`default` index). Hosting your own plugin index is not recommended, unless you
+have a use case that specifically calls for it, such as:
 
-- your plugin is not accepted to `krew-index`
-- you want full control over the distribution lifecycle of your own plugin
-- you want to run a _private_ plugin index in your organization (e.g. to be
-  installed on developer machines)
+- Your plugin is not accepted to `krew-index`
+- You want full control over the distribution lifecycle of your own plugin
+- You want to run a _private_ plugin index in your organization (e.g.
+  installations on developer machines)
 
 Hosting your own custom index is simple:
 
 - Custom index repositories must be `git` repositories.
-- Your clients should have read access to the repository (if the repository
+- Your clients should have 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).
+  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 plugin manifests are valid YAML and passes Krew manifest validation
+  directory (not in a subdirectory).
+- Ensure plugin manifests are valid YAML and pass 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).

site/content/docs/developer-guide/develop/best-practices.md

@@ -6,11 +6,11 @@ weight: 300
 
 {{< toc >}}
 
-This guide lists practices to use while developing `kubectl` plugins. Before
-submitting your plugin to Krew, please review these
+This guide describes practices to use when developing `kubectl` plugins. Before
+submitting your plugin to Krew, please review these practices.
 
-While Krew project does not enforce any strict guidelines about how a plugin
-works, using some of these practices can help your plugin work for more users
+While the Krew project team does not strictly enforce guidelines about how a plugin
+works, abiding by these practices can help your plugin work for more users
 and behave more predictably.
 
 ## Choosing a language
@@ -20,17 +20,17 @@ Most `kubectl` plugins are written in Go or as bash scripts.
 If you are planning to write a plugin with Go, check out:
 
 - [client-go]: a Go SDK to work with Kubernetes API and kubeconfig files
-- [cli-runtime]: Provides packages to share code with `kubectl` for printing output or [sharing command-line options][cli-opts]
-- [sample-cli-plugin]: An example plugin implementation in Go
+- [cli-runtime]: a set of packages to share code with `kubectl` for printing output or [sharing command-line options][cli-opts]
+- [sample-cli-plugin]: an example plugin implementation in Go
 
 ## Consistency with kubectl {#kubectl-options}
 
-Krew does not try to impose any rules in terms of the shape of your plugin.
+Krew does not impose any rules in terms of the shape of your plugin.
 
-However, if you use the command-line options with `kubectl`, you can make your
+However, if you support the common command-line options with `kubectl`, you can make your
 users’ lives easier.
 
-For example, it is recommended you use the following command line flags used by
+For example, it is recommended that you support the following command-line flags used by
 `kubectl`:
 
 - `-h`/`--help`
@@ -44,8 +44,8 @@ support the global command-line flags listed in `kubectl options` (e.g.
 ## Import authentication plugins (Go) {#auth-plugins}
 
 By default, plugins that use [client-go]
-cannot authenticate to Kubernetes clusters on many cloud providers. To overcome
-this, add the following import to somewhere in your binary:
+cannot authenticate to Kubernetes clusters on many cloud providers. To address
+this, include the following import in your plugin:
 
 ```go
 import _ "k8s.io/client-go/plugin/pkg/client/auth"
@@ -56,22 +56,21 @@ import _ "k8s.io/client-go/plugin/pkg/client/auth"
 [cli-opts]: https://godoc.org/k8s.io/cli-runtime/pkg/genericclioptions
 [sample-cli-plugin]: https://github.com/kubernetes/sample-cli-plugin
 
-## Revise usage/help messages with `kubectl` prefix {#help-messages}
+## Revise usage and help messages with the `kubectl` prefix {#help-messages}
 
-Users discover how to use your plugin by calling it without any arguments (which
-might trigger a help message), or `-h`/`--help` options.
+Many users will discover how to use your plugin by calling it without any arguments (which
+might trigger a help message), or with `-h`/`--help` arguments.
 
-Therefore, change your usage strings to show `kubectl ` prefix before the plugin
+Therefore, it is helpful to change your usage strings to show the `kubectl ` prefix before the plugin
 name. For example
 
 ```text
 Usage:
   kubectl popeye [flags]
 ```
 
-To determine whether an executable is running as a plugin or not, you can look
-at argv[0], which would have the `kubectl-` prefix. To determine whether your
-program is running as a kubectl plugin or not:
+To determine if your executable is running as a `kubectl` plugin, you can look
+at `argv[0]`, which will include the `kubectl-` prefix
 
 - **Go:**
 

site/content/docs/developer-guide/develop/naming-guide.md

@@ -4,81 +4,79 @@ slug: naming-guide
 weight: 200
 ---
 
-This document explains the best practices and recommendations for naming your
-kubectl plugins.
+This document describes guidelines for naming your kubectl plugins.
 
 These guidelines are used for reviewing the plugins [submitted to Krew]({{<ref
 "../release/submitting-to-krew.md">}}).
 
-##### _Punctuation_
+##### _Use lowercase and hyphens_
 
 Plugin names must be all lowercase and separate words with hyphens.
 **Don't** use camelCase, PascalCase, or snake_case; use
 [kebab-case](http://wiki.c2.com/?KebabCase).
 
-- **DON'T:** `kubectl OpenSvc`
-- **DO:** `kubectl open-svc`
+- **NO:** `kubectl OpenSvc`
+- **YES:** `kubectl open-svc`
 
 ##### _Be specific_
 
-Plugin names should not be verbs/nouns that are generic, already overloaded, or
-possibly can be used for broader purposes by another plugin.
+Plugin names should not be verbs or nouns that are generic, already overloaded, or
+likely to be used for broader purposes by another plugin.
 
-- **DON'T:** `kubectl login`: Tries to put dibs on the word.
-- **DO:** `kubectl gke-login`.
+- **NO:** `kubectl login` (Too broad)
+- **YES:** `kubectl gke-login`
 
 Also:
 
-- **DON'T:** `kubectl ui`: Should be used only for Kubernetes Dashboard.
-- **DO:** `kubectl gke-ui`.
+- **NO:** `kubectl ui` (Should be used only for Kubernetes Dashboard)
+- **YES:** `kubectl gke-ui`
 
 ##### _Be unique_
 
-Try to find a unique name for your plugin that differentiates you from other
-possible plugins doing the same job.
+Find a unique name for your plugin that differentiates it from other
+plugins that perform a similar function.
 
-- **DON'T:** `kubectl view-logs`: Unclear how it is different than the builtin
-  "logs" command, or many other tools for viewing logs.
-- **DO:** `kubectl tailer`:  Unique name, points to the underlying
+- **NO:** `kubectl view-logs` (Unclear how it is different from the builtin
+  "logs" command, or many other tools for viewing logs)
+- **YES:** `kubectl tailer` (Unique name, points to the underlying)
   tool name.
 
-##### _Use Verbs/Resource Types_
+##### _Use Verbs and Resource Types_
 
 If the name does not make it clear (a) what verb the plugin is doing on a
 resource, or (b) what kind of resource it's doing the action on, consider
 clarifying unless it is obvious.
 
-- **DON'T:** `kubectl service`: Unclear what this plugin is doing with
+- **NO:** `kubectl service` (Unclear what this plugin is doing with)
   service.
-- **DON'T:** `kubectl open`: Unclear what it is opening.
-- **DO:** `kubectl open-svc`: It is clear the plugin will open a service.
+- **NO:** `kubectl open` (Unclear what the plugin is opening)
+- **YES:** `kubectl open-svc` (It is clear the plugin will open a service)
 
 ##### _Prefix Vendor Identifiers_
 
-Use the vendor-specific strings as prefix, separated with a dash. This makes it
+Use vendor-specific strings as prefix, separated with a dash. This makes it
 easier to search/group plugins that are about a specific vendor.
 
-- **DON'T:** `kubectl ui-gke`: Makes it harder to search or locate in a
-  plugin list.
-- **DO:** `kubectl gke-ui`: Will show up next to other gke-* plugins.
+- **NO:** `kubectl ui-gke` (Makes it harder to search or locate in a
+  plugin list)
+- **YES:** `kubectl gke-ui` (Will show up next to other gke-* plugins)
 
 ##### _Avoid repeating kube[rnetes]_
 
-Plugin names should not repeat kube- or kubernetes- prefixes to avoid
+Plugin names should not include "kube-" or "kubernetes-" prefixes to avoid
 stuttering.
 
-- **DON'T:** `kubectl kube-node-admin`: "kubectl " already has "kube" in
-  it.
-- **DO:** `kubectl node-admin`.
+- **NO:** `kubectl kube-node-admin` ("kubectl " already has "kube" in it)
+- **YES:** `kubectl node-admin`
 
-##### _Avoid Resource Acronyms_
+##### _Avoid Resource Acronyms and Abbreviations_
 
 Using kubectl acronyms for API resources (e.g. svc, ing, deploy, cm) reduces
-readability and discoverability of a plugin more than it is saving keystrokes.
+the readability and discoverability of a plugin, which is more important
+than the few keystrokes saved.
 
-- **DON'T:** `kubectl new-ing`: Hard to spot and the plugin is for
-  Ingress.
-- **DO:** `kubectl debug-ingress`.
+- **NO:** `kubectl new-ing` (Unclear that the plugin is for Ingress)
+- **YES:** `kubectl debug-ingress`
 
-If you have suggestions to this guide, open an issue or send a pull request, as
-this is an open topic of debate with a lot of gray areas.
+Note: If you have suggestions for improving this guide, open an issue or send a
+pull request, as this is a topic under active development.

site/content/docs/developer-guide/develop/plugin-development.md

@@ -10,26 +10,26 @@ on this topic.
 
 To summarize the documentation, the procedure is to:
 
-- Write an executable binary, named `kubectl-foo` to have a plugin that can be
+- Create an executable binary, named `kubectl-foo` (for example) to have a plugin that can be
   invoked as `kubectl foo`.
-- Place the executable to a directory listed in user’s `PATH` environment
-  variable. (Plugins distributed with Krew don't need to worry  about this).
-- You can't overwrite a builtin `kubectl` command with a plugin.
+- Place the executable in a directory that is listed in the user’s `PATH` environment
+  variable. (You don't have to do this for plugins distributed with Krew).
+- You can't overwrite a built-in `kubectl` command with a plugin.
 
-> **If you are writing a plugin in Go:** Consider using the [cli-runtime] project
+> **Note:** If you are writing a plugin in Go, consider using the [cli-runtime] project
 > which is designed to provide the same command-line arguments, kubeconfig
 > parser, Kubernetes API REST client, and printing logic. Look at
 > [sample-cli-plugin] for an example of a kubectl plugin.
 >
-> Also, there's an unofficial [GitHub template
+> Also, see the unofficial [GitHub template
 > repo](https://github.com/replicatedhq/krew-plugin-template) for a Krew plugin
-> in Go that implements some best practices mentioned in this guide, and helps
-> you automate releases using GoReleaser to create release when a tag is pushed.
+> in Go that implements some best practices covered later in this guide, and helps
+> you automate releases using GoReleaser to create a release when a tag is pushed.
 
 [cli-runtime]: https://github.com/kubernetes/cli-runtime/
 [sample-cli-plugin]: https://github.com/kubernetes/sample-cli-plugin
 
-While developing a plugin, make sure you check out:
+When developing your own plugins, make sure you check out:
 
 - [Plugin naming guide]({{<ref "naming-guide.md">}}) to choose a good name
   for your plugin

site/content/docs/developer-guide/distributing-with-krew.md

@@ -3,37 +3,37 @@ title: Distributing plugins on Krew
 weight: 110
 ---
 
-## Why Krew? {#why}
+## Why use Krew for distribution? {#why}
 
-To install a kubectl plugin to a user’s machine, all you need to do is to place
-an executable in user’s `PATH` prefixed with `kubectl-` name. At this point, you
-might consider some other options such as:
+On the surface, installing a kubectl plugin seems simple enough -- all you need to do is to place
+an executable in the user’s `PATH` prefixed with `kubectl-` -- that you may be
+considering some other alternatives to Krew, such as:
 
-- have the user manually download the plugin binary and set up somewhere in
-  `PATH`
-- distribute the plugin executable using an OS package manager, like Homebrew
-  (macOS), apt/yum (Linux) or Chocolatey (Windows)
-- distribute the plugin executable using a language package manager (e.g. npm,
+- Having the user manually download the plugin executable and move it to some directory in
+  the `PATH`
+- Distributing the plugin executable using an OS package manager, like Homebrew
+  (macOS), apt/yum (Linux), or Chocolatey (Windows)
+- Distributing the plugin executable using a language package manager (e.g. npm or
   go get)
 
-While these approaches might work some shortcomings to think about are:
+While these approaches are not necessarily unworkable, potential drawbacks to consider include:
 
-- how to ship updates to users (in case of manual installation)
-- need to package a plugin for multiple platforms (macOS, Linux, Windows)
-- your users need to download the language package manager (go, npm)
-- what if you change the implementation language (e.g. move from npm to another package manager)
+- How to get updates to users (in the case of manual installation)
+- How to package a plugin for multiple platforms (macOS, Linux, and Windows)
+- How to ensure your users have the appropriate language package manager (go, npm)
+- How to handle a change to the implementation language (e.g. a move from npm to another package manager)
 
 Krew solves these problems cleanly for all kubectl plugins, since it's designed
-**specifically to address these shortcomings**: With Krew, you write a plugin
-manifest once and have a plugin that can be installed on all platforms
+**specifically to address these shortcomings**. With Krew, after you write a plugin
+manifest once your plugin can be installed on all platforms
 without having to deal with their package managers.
 
 ## Steps to get started
 
 Once you [develop]({{< ref "develop/plugin-development.md" >}}) a `kubectl`
-plugin, here are the steps you need to follow to distribute your plugin on Krew:
+plugin, follow these steps to distribute your plugin on Krew:
 
 1. Package your plugin into an archive file (`.tar.gz` or `.zip`).
 1. Make the archive file publicly available (e.g. as GitHub release files).
-1. Write [Krew plugin manifest]({{< ref "plugin-manifest.md" >}}) file.
+1. Write a [Krew plugin manifest]({{< ref "plugin-manifest.md" >}}) file.
 1. [Submit your plugin to krew-index]({{< ref "release/../release/submitting-to-krew.md" >}}).

site/content/docs/developer-guide/example-plugin-manifests.md

@@ -5,11 +5,11 @@ weight: 200
 ---
 
 Learning how to [write plugin manifests]({{< ref "plugin-manifest.md" >}})
-can be a time-consuming tasks.
+can be a time-consuming task.
 
-Krew encourages you to copy and adapt plugin manifests of [existing
-plugins][list]. Since these are already reviewed and approved, your plugin can
-be accepted more quickly.
+The Krew team encourages you to copy and adapt plugin manifests of [existing
+plugins][list]. Since these are already reviewed and approved, your plugin is
+likely to be accepted more quickly.
 
 * **Go:**
   - [tree](https://github.com/kubernetes-sigs/krew-index/blob/master/plugins/tree.yaml):

site/content/docs/developer-guide/installing-locally.md

@@ -5,34 +5,34 @@ weight: 300
 ---
 
 After you have written your [plugin manifest]({{< ref "plugin-manifest.md" >}})
-archived your plugin into a `.zip` or `.tar.gz` file, you can now test whether
+and archived your plugin into a `.zip` or `.tar.gz` file, you can verify that
 your plugin installs correctly with Krew by running:
 
 ```sh
 {{<prompt>}}kubectl krew install --manifest=foo.yaml --archive=foo.tar.gz
 ```
 
-- `--manifest` flag specifies a custom manifest rather than picking it up from
+- The `--manifest` flag specifies a custom manifest rather than using
   the default [krew index][index]
 - `--archive` overrides the download `uri:` specified in the plugin manifest and
   uses a local `.zip` or `.tar.gz` file instead.
 
 If the installation **fails**, run the command again with `-v=4` flag to see the
-verbose logs and inspect what went wrong.
+verbose logs and examine what went wrong.
 
-If your installation **succeeds**, you should now be able to run your plugin.
+If the installation **succeeds**, you should now be able to run your plugin.
 
-If you made your archive file available to download on the Internet, run the
+If you made your archive file available for download on the Internet, run the
 same command without the `--archive` option and actually test downloading the
 file from the specified `uri` and validate its `sha256` sum is correct.
 
-After you have tested your plugin, uninstall it with `kubectl krew uninstall foo`.
+After you have tested your plugin installation, uninstall it with `kubectl krew uninstall foo`.
 
 ### Testing other platforms
 
-If you need other `platforms` definitions that don't match your current machine,
-you can use `KREW_OS` and/or `KREW_ARCH` environment variables to override what
-OS/architecture Krew thinks it's running on.
+If you need to test other `platforms` definitions that don't match your current machine,
+you can use `KREW_OS` and `KREW_ARCH` environment variables to override the
+OS and architecture that Krew thinks it's running on.
 
 For example, if you're on a Linux machine, you can test Windows installation
 with: