Some files had conflict with some URL - fixed now

9 files changed, 693 insertions, 12 deletions

diff --git a/contributors/guide/OWNERS b/contributors/guide/OWNERS
index a9abb261..745a9be0 100644
--- a/contributors/guide/OWNERS
+++ b/contributors/guide/OWNERS
@@ -1,3 +1,5 @@
+# See the OWNERS docs at https://go.k8s.io/owners
+
 reviewers:
   - castrojo
   - guineveresaenger
@@ -8,6 +10,7 @@ reviewers:
 approvers:
   - castrojo
   - parispittman
+  - guineveresaenger
 labels:
   - sig/contributor-experience
   - area/contributor-guide
diff --git a/contributors/guide/README.md b/contributors/guide/README.md
index 08bbdf95..e91eb0fc 100644
--- a/contributors/guide/README.md
+++ b/contributors/guide/README.md
@@ -217,14 +217,14 @@ When reviewing PRs from others [The Gentle Art of Patch Review](http://sage.thes
 ## Testing
 
 Testing is the responsibility of all contributors and is in part owned by all SIGss, but is also coordinated by [sig-testing](/sig-testing). 
-Refer to the [Testing Guide](/contributors/devel/testing.md) for more information.
+Refer to the [Testing Guide](/contributors/devel/sig-testing/testing.md) for more information.
 
 There are multiple types of tests.
 The location of the test code varies with type, as do the specifics of the environment needed to successfully run the test:
 
 * Unit: These confirm that a particular function behaves as intended.  Golang includes a native ability for unit testing via the [testing](https://golang.org/pkg/testing/) package.  Unit test source code can be found adjacent to the corresponding source code within a given package.  For example: functions defined in [kubernetes/cmd/kubeadm/app/util/version.go](https://git.k8s.io/kubernetes/cmd/kubeadm/app/util/version.go) will have unit tests in [kubernetes/cmd/kubeadm/app/util/version_test.go](https://git.k8s.io/kubernetes/cmd/kubeadm/app/util/version_test.go).  These are easily run locally by any developer on any OS.
 * Integration: These tests cover interactions of package components or interactions between kubernetes components and some other non-kubernetes system resource (eg: etcd).  An example would be testing whether a piece of code can correctly store data to or retrieve data from etcd.  Integration tests are stored in [kubernetes/test/integration/](https://git.k8s.io/kubernetes/test/integration).  Running these can require the developer set up additional functionality on their development system.
-* End-to-end ("e2e"): These are broad tests of overall system behavior and coherence.  These are more complicated as they require a functional kubernetes cluster built from the sources to be tested. A separate [document detailing e2e testing](/contributors/devel/e2e-tests.md) and test cases themselves can be found in [kubernetes/test/e2e/](https://git.k8s.io/kubernetes/test/e2e).
+* End-to-end ("e2e"): These are broad tests of overall system behavior and coherence.  These are more complicated as they require a functional kubernetes cluster built from the sources to be tested. A separate [document detailing e2e testing](/contributors/devel/sig-testing/e2e-tests.md) and test cases themselves can be found in [kubernetes/test/e2e/](https://git.k8s.io/kubernetes/test/e2e).
 * Conformance: These are a set of testcases, currently a subset of the integration/e2e tests, that the Architecture SIG has approved to define the core set of interoperable features that all Kubernetes deployments must support. For more information on Conformance tests please see the [Conformance Testing](/contributors/devel/sig-architecture/conformance-tests.md) Document.
 
 Continuous integration will run these tests either as pre-submits on PRs, post-submits against master/release branches, or both.  
diff --git a/contributors/guide/coding-conventions.md b/contributors/guide/coding-conventions.md
index 87e6432f..880c1833 100644
--- a/contributors/guide/coding-conventions.md
+++ b/contributors/guide/coding-conventions.md
@@ -61,7 +61,7 @@ following Go conventions - `stateLock`, `mapLock` etc.
 
     - [Kubectl conventions](/contributors/devel/kubectl-conventions.md)
 
-    - [Logging conventions](/contributors/devel/logging.md)
+    - [Logging conventions](/contributors/devel/sig-instrumentation/logging.md)
 
 ## Testing conventions
 
@@ -72,7 +72,7 @@ tests
 example, see [TestNamespaceAuthorization](https://git.k8s.io/kubernetes/test/integration/auth/auth_test.go)
 
   - Significant features should come with integration (test/integration) and/or
-[end-to-end (test/e2e) tests](/contributors/devel/e2e-tests.md)
+[end-to-end (test/e2e) tests](/contributors/devel/sig-testing/e2e-tests.md)
     - Including new kubectl commands and major features of existing commands
 
   - Unit tests must pass on macOS and Windows platforms - if you use Linux
@@ -86,7 +86,7 @@ required when your code does not compile on Windows).
 asynchronous thing to happen (e.g. wait for 1 seconds and expect a Pod to be
 running). Wait and retry instead.
 
-  - See the [testing guide](/contributors/devel/testing.md) for additional testing advice.
+  - See the [testing guide](/contributors/devel/sig-testing/testing.md) for additional testing advice.
 
 ## Directory and file conventions
 
diff --git a/contributors/guide/contributor-cheatsheet.md b/contributors/guide/contributor-cheatsheet.md
index 180a368f..320cd980 100644
--- a/contributors/guide/contributor-cheatsheet.md
+++ b/contributors/guide/contributor-cheatsheet.md
@@ -20,7 +20,7 @@ A list of common resources when contributing to Kubernetes.
 - [GitHub labels](https://go.k8s.io/github-labels)
 - [Release Buckets](https://gcsweb.k8s.io/gcs/kubernetes-release/)
 - Developer Guide
-  - [Cherry Picking Guide](/contributors/devel/cherry-picks.md)
+  - [Cherry Picking Guide](/contributors/devel/sig-release/cherry-picks.md)
 - [Kubernetes Code Search](https://cs.k8s.io/), maintained by [@dims](https://github.com/dims)
 
 
diff --git a/contributors/guide/github-workflow.md b/contributors/guide/github-workflow.md
index 221a7921..cc1e7e8f 100644
--- a/contributors/guide/github-workflow.md
+++ b/contributors/guide/github-workflow.md
@@ -149,17 +149,17 @@ make test
 make test WHAT=./pkg/api/helper GOFLAGS=-v
 
 # Run integration tests, requires etcd
-# For more info, visit https://git.k8s.io/community/contributors/devel/testing.md#integration-tests
+# For more info, visit https://git.k8s.io/community/contributors/devel/sig-testing/testing.md#integration-tests
 make test-integration
 
 # Run e2e tests by building test binaries, turn up a test cluster, run all tests, and tear the cluster down
 # Equivalent to: go run hack/e2e.go -- -v --build --up --test --down
 # Note: running all e2e tests takes a LONG time! To run specific e2e tests, visit:
-# https://git.k8s.io/community/contributors/devel/e2e-tests.md#building-kubernetes-and-running-the-tests
+# https://git.k8s.io/community/contributors/devel/sig-testing/e2e-tests.md#building-kubernetes-and-running-the-tests
 make test-e2e
 ```
 
-See the [testing guide](/contributors/devel/testing.md) and [end-to-end tests](/contributors/devel/e2e-tests.md)
+See the [testing guide](/contributors/devel/sig-testing/testing.md) and [end-to-end tests](/contributors/devel/sig-testing/e2e-tests.md)
 for additional information and scenarios.
 
 Run `make help` for additional information on these make targets.
diff --git a/contributors/guide/issue-triage.md b/contributors/guide/issue-triage.md
index ff67ba3e..879648a9 100644
--- a/contributors/guide/issue-triage.md
+++ b/contributors/guide/issue-triage.md
@@ -206,7 +206,7 @@ block the release on it. A few days before release, we will probably move all
 that milestone in bulk.
 
 More information can be found in the developer guide section for
-[targeting issues and PRs to a milestone release](/contributors/devel/release.md).
+[targeting issues and PRs to a milestone release](/contributors/devel/sig-release/release.md).
 
 ## Closing issues
 Issues that are identified as a support request, duplicate, not-reproducible
diff --git a/contributors/guide/pull-requests.md b/contributors/guide/pull-requests.md
index a24310a6..a9c26086 100644
--- a/contributors/guide/pull-requests.md
+++ b/contributors/guide/pull-requests.md
@@ -115,7 +115,7 @@ The GitHub robots will add and remove the `do-not-merge/hold` label as you use t
 
 ## Pull Requests and the Release Cycle
 
-If a pull request has been reviewed, but held or not approved, it might be due to the current phase in the [Release Cycle](/contributors/devel/release.md). Occasionally, a SIG may freeze their own code base when working towards a specific feature or goal that could impact other development. During this time, your pull request could remain unmerged while their release work is completed.
+If a pull request has been reviewed, but held or not approved, it might be due to the current phase in the [Release Cycle](/contributors/devel/sig-release/release.md). Occasionally, a SIG may freeze their own code base when working towards a specific feature or goal that could impact other development. During this time, your pull request could remain unmerged while their release work is completed.
 
 If you feel your pull request is in this state, contact the appropriate [SIG](https://git.k8s.io/community/sig-list.md) or [SIG-Release](https://git.k8s.io/sig-release) for clarification.
 
diff --git a/contributors/guide/release-notes.md b/contributors/guide/release-notes.md
index 655dff1c..81dca597 100644
--- a/contributors/guide/release-notes.md
+++ b/contributors/guide/release-notes.md
@@ -30,4 +30,4 @@ For pull requests that don't need to be mentioned at release time, use the `/rel
 
 To see how to format your release notes, view the kubernetes/kubernetes [pull request template](https://git.k8s.io/kubernetes/.github/PULL_REQUEST_TEMPLATE.md) for a brief example. Pull Request titles and body comments can be modified at any time prior to the release to make them friendly for release notes.
 
-Release notes apply to pull requests on the master branch. For cherry-pick pull requests, see the [cherry-pick instructions](/contributors/devel/cherry-picks.md). The only exception to these rules is when a pull request is not a cherry-pick and is targeted directly to the non-master branch.  In this case, a `release-note-*` label is required for that non-master pull request.
+Release notes apply to pull requests on the master branch. For cherry-pick pull requests, see the [cherry-pick instructions](/contributors/devel/sig-release/cherry-picks.md). The only exception to these rules is when a pull request is not a cherry-pick and is targeted directly to the non-master branch.  In this case, a `release-note-*` label is required for that non-master pull request.
diff --git a/contributors/guide/style-guide.md b/contributors/guide/style-guide.md
new file mode 100644
index 00000000..05ccbb04
--- /dev/null
+++ b/contributors/guide/style-guide.md
@@ -0,0 +1,678 @@
+---
+title: Documentation Style Guide
+---
+
+# Documentation Style Guide
+
+This style guide is for content in the Kubernetes github [community repository].
+It is an extension of the [Kubernetes documentation style-guide].
+
+These are **guidelines**, not rules. Use your best judgement.
+
+- [Cheatsheet](#cheatsheet)
+- [Content design, formatting, and language](#content-formatting-and-language)
+  - [Contact information](#contact-information)
+  - [Dates and times](#dates-and-times)
+  - [Diagrams, images and other assets](#diagrams-images-and-other-assets)
+  - [Document Layout](#document-layout)
+  - [Formatting text](#formatting-text)
+  - [Language, grammar, and tone](#language-grammar-and-tone)
+  - [Moving a document](#moving-a-document)
+  - [Punctuation](#punctuation)
+  - [Quotation](#quotation)
+- [Markdown formatting](#markdown-and-formatting)
+  - [Code Blocks](code-blocks)
+  - [Emphasis](#emphasis)
+  - [Headings](#headings)
+  - [Horizontal Lines](#horizontal-lines)
+  - [Line Length](#line-length)
+  - [Links](#links)
+  - [Lists](#lists)
+  - [Metadata](#metadata)
+  - [Tables](#tables)
+- [Attribution](#attribution)
+
+
+## Cheatsheet
+
+### Cheatsheet: Content design, formatting, and language
+
+**[Contact information:](#contact-information)**
+- Use official Kubernetes contact information.
+
+**[Dates and times:](#dates-and-times)**
+- Format dates as `month day, year`. (December 13, 2018)
+- When conveying a date in numerical form, use [ISO 8601] Format: `yyyy-mm-dd`.
+- Use the 24 hour clock when referencing time.
+- Times for single events (example: KubeCon) should be expressed in an absolute
+  time zone such as Pacific Standard Time (PST) or Coordinated Universal Time
+  (UTC).
+- Times for reoccurring events should be expressed in a time zone that follows
+  Daylight Savings Time (DST) such as Pacific Time (PT) or Eastern Time (ET).
+- Supply a link to a globally available time zone converter service.
+  - `http://www.thetimezoneconverter.com/?t=<TIME REFERENCE>&tz=<TZ REFERENCE>`
+
+**[Diagrams, images and other assets:](#diagrams-images-and-other-assets)**
+- Images and other assets should be stored in the same directory as the document
+  that is referencing it.
+- Filenames should be lowercase and descriptive of what they are referencing.
+- Avoid excessively large images or include a smaller one while linking to a
+  higher resolution version of the same image.
+- Use the [Kubernetes icon set] for architectural diagrams.
+
+**[Document Layout:](#document-layout)**
+- Documents should follow the general template of:
+  - Document metadata (if appropriate).
+  - Title in `H1` (a single `#`).
+  - A brief description or summary of the document.
+  - A table of contents.
+  - The general body of document.
+- Do not repeat content. Instead link back to the canonical source.
+- Large content or topic shifts should be separated with a horizontal rule.
+
+**[Formatting text:](#formatting-text)**
+- API objects:
+  - Follow the established [API naming convention] when referring to API Objects.
+  - Do not split API object names into their components.
+  - Use `code` style for API objects or object parameters.
+- Use **bold text** for user interface elements.
+- Use _italics_ to emphasize a new topic or subject for the first time.
+- Use angle brackets (`<` and `>`) to enclose a placeholder reference.
+- Apply `code` styling to:
+  - Filenames, directories, and paths.
+  - Command line examples and flags.
+  - Object field names.
+
+**[Language, grammar and tone:](#language)**
+- Documentation should be written in English.
+- Prefer an active voice and present tense when possible.
+- Use simple and direct language.
+- Use gender-neutral language.
+- Avoid personal pronouns ("I," "we," "us," "our," and "ours").
+- Address the reader as "you" instead of "we".
+- Do not use Latin phrases.
+- Avoid jargon and idioms.
+- If using acronyms, ensure they are clearly defined in the same document.
+- If using an abbreviation, spell it out the first time it is used in the
+  document unless it is commonly known. (example: TCP/IP)
+
+**[Moving a document:](#moving-a-document)**
+- Use `[git-mv]` to move documents.
+- Commit moved documents separately from any other changes.
+- When a document has moved, leave a tombstone file with a removal date in its
+  place.
+  
+**[Punctuation:](#punctuation)**
+- Do not use punctuation in headings.
+- End full sentences with a period.
+  - **Exception:** When a sentence ends with a URL or if the text would be
+    unclear if the period is a part of the previous object or word.
+- Add a single space after a period when beginning a new sentence.
+- Avoid usage of exclamation points unless they are a part of a code example.
+- Use an [Oxford comma] when a list contains 3 or more elements.
+
+**[Quotation:](#quotes)**
+- Use double-quotation marks (`" "`) over single-quotation marks (`' '`).
+  - **Exception:** In code snippets where quotation marks have specific meaning.
+  - **Exception:** When nesting quotation marks inside another set of quotation
+    marks.
+- Punctuation should be outside of quotation marks following the international
+  (British) standard.
+
+
+### Cheatsheet: Markdown
+
+**[Code blocks:](#code-blocks)**
+- When possible, reference the language at the beginning of a Code Block.
+- When a code block is used to reference a shell, do not include the command
+  prompt (`$`).
+  - **Exception:** When a code block is used to display raw shell output.
+- Separate commands from output.
+
+**[Emphasis:](#emphasis)**
+- Use two asterisks (`**`) for **Bold** text.
+- Use an underscore (`_`) for _Italics_.
+- Use two tildes (`~~`) for ~~Strikethrough~~.
+ 
+**[Headings:](#headings)**
+- Use a single `H1` (`#`) Heading per document.
+  - **Exception:** `H1` may be used multiple times in the same document when
+    there is a large content shift or "chapter" change.
+- Follow the Header hierarchy of `H2` > `H3` > `H4` > `H5` > `H6`.
+- Use sentence-style capitalization in titles (first word and proper nouns).
+- Avoid using special characters.
+- Leave exactly 1 new line after a heading.
+- Avoid using links in headings.
+
+**[Horizontal rules:](#horizontal-lines)**
+- Use three dashes (`---`) to denote a horizontal rule.
+- Use a horizontal rule (`---`) to logically separate large sections.
+
+**[Line length:](#line-length)**
+- Prefer an 80 character line limit.
+
+**[Links:](#links)**
+- Prefer using reference style links over inline style links.
+- When linking within the same directory, use a relative link.
+- When linking to a document outside of the current directory, use the absolute
+  path from the root of the repository.
+- When linking to a file in another Kubernetes github repository, use the
+  `k8s.io` url shortener.
+  - git.k8s.io -> github.com/kubernetes
+  - sigs.k8s.io -> github.com/kubernetes-sigs
+
+**[Lists:](#lists)**
+- Capitalize the first character of each entry unless the item is explicitly
+  case sensitive.
+- End each entry with a period if it is a sentence or phrase.
+- Use a colon (`:`) to separate a list item name from the explanatory text.
+- Leave a blank line after each list.
+- Use `-` for unordered lists.
+- For ordered lists repeating `1.` may be used.
+- When inserting a code block into an ordered list, indent (space) an additional
+  two times.
+
+**[Metadata:](metadata)**
+- If the document is intended to be surfaced on the Contributor Site; include a
+  yaml metadata header at the beginning of the document.
+- Metadata must include the `title` attribute.
+
+**[Tables:](#tables)**
+- Use tables for structured information.
+- Tables do not need to adhere to the suggested line length.
+- Avoid long inline links.
+- Do not use excessively wide tables.
+
+---
+
+## Content design, formatting, and language
+
+### Contact information
+
+- Use official Kubernetes contact information.
+  - Use official community contact email addresses. There should be no personal
+    or work contact information included in public documentation; instead use
+    addresses like the [SIG Google groups] or managed accounts such as
+    community@kubernetes.io. 
+  - **Good example:** community@kubernetes.io
+  - **Bad example:** bob@example.com
+
+
+### Dates and times
+
+The Kubernetes Contributor Community spans many regions and time zones.
+Following a consistent pattern and avoiding shorthand improves the readability
+for every member.
+
+- Format dates as `month day, year`. (December 13, 2018)
+  - **Good example:** October 24, 2018
+  - **Bad example:** 10/24/18
+- When conveying a date in numerical form, use [ISO 8601] Format: `yyyy-mm-dd`.
+  - **Good example:** 2018-10-24
+  - **Bad example:** 10/24/18
+- Use the 24 hour clock when referencing time.
+  - **Good example:** 15:30
+  - **Bad example:** 3:30pm
+- Times for single events (example: KubeCon) should be expressed in an absolute
+  time zone such as Pacific Standard Time (PST) or Coordinated Universal Time
+  (UTC).
+  - **Good example:** The Seattle Contributor Summit starts at 9:00 PST
+  - **Bad example:** The Seattle Contributor Summit starts at 9:00 PT
+- Times for reoccurring events should be expressed in a time zone that follows
+  Daylight Savings Time (DST) such as Pacific Time (PT) or Eastern Time (ET).
+  - Times that follow DST are used as they adjusts automatically. If UTC or
+    other non-DST compatible time zones were used, content would have to be
+    updated multiple times per year to adjust times.
+  - **Good example:** 13:30 PT
+  - **Bad example:** 16:30 EST
+- Supply a link to a globally available time zone converter service.
+  - `http://www.thetimezoneconverter.com/?t=<TIME REFERENCE>&tz=<TZ REFERENCE>`
+
+  ```
+  The weekly SIG meeting is at [13:30 PT].
+
+  [13:30 PT]: http://www.thetimezoneconverter.com/?t=13:30&tz=PT%20%28Pacific%20Time%29
+  ```
+
+
+### Diagrams, images and other assets
+
+- Images and other assets should be stored in the same directory as the document
+  that is referencing it.
+- Filenames should be lowercase and descriptive of what they are referencing.
+  - **Good example:** `deployment-workflow.jpg`
+  - **Bad example:** `image1.jpg`
+- Avoid excessively large images or include a smaller one while linking to a
+  higher resolution version of the same image.
+- Use the [Kubernetes icon set] for architectural diagrams.
+
+
+### Document Layout
+
+Adhering to a standard document layout ensures that each page can intuitively 
+be navigated once a reader is familiar with the standard layout.
+
+- Documents should follow the general template of:
+  - Document metadata (if appropriate).
+  - Title in `H1` (a single `#`).
+  - A brief description or summary of the document.
+  - A table of contents.
+  - The general body of document.
+- Do not repeat content. Instead link back to the canonical source.
+  - It is easy for content to become out of sync if it is maintained in
+    multiple places. Linking back to the canonical source ensures that the
+    documentation will be accurate and up to date.
+- Large content or topic shifts should be separated with a horizontal rule.
+
+
+### Formatting text
+
+The formatting guidelines have been selected to mirror or augment the
+[Kubernetes documentation style-guide]. Remaining consistent across the
+different content sources improves the overall readability and understanding of
+the documentation being presented in addition to giving the project a unified
+external appearance.
+
+- API objects:
+  - Follow the established [API naming convention] when referring to API Objects.
+  - Do not split API object names into their components.
+    - **Good example:** A `Pod` contains a `PodTemplateSpec`.
+    - **Bad example:** A `Pod` contains a `Pod Template Spec`.
+  - Use `code` style for API objects or object parameters.
+    - **Good example:** A `Deployment` contains a `DeploymentSpec`.
+    - **Bad example:**  A Deployment contains a DeploymentSpec.
+- Use angle brackets (`<` and `>`) to surround a placeholder references.
+  - **Good example:** `kubectl describe pod <pod-name>`
+  - **Bad example:** `kubectl describe pod pod-name`
+- Use **bold text** for user interface elements.
+  - **Good example:** Select **Other**.
+  - **Bad example:** Select "Other".
+- Use _italic text_ to emphasize a new subject for the first time.
+  - **Good example:** A _cluster_ is a set of nodes.
+  - **Bad example:** A "cluster" is a set of nodes.
+- `Code` styling should be applied to:
+  - Filenames, directories, and paths.
+    - **Good example:** The default manifest path is `/etc/kubernetes/manifests`.
+    - **Bad example:** The default manifest path is /etc/kubernetes/manifests.
+  - Command line examples and flags.
+    - **Good example:** The flag `--advertise-address` is used to denote the
+      IP address on which to advertise the apiserver to members of the cluster.
+    - **Bad example:** The flag --advertise-address is used to denote the IP
+      address on which to advertise the apiserver to members of the cluster.
+  - Object field names.
+    - **Good example:** Set the `externalTrafficPolicy` to Local.
+    - **Bad example:** Set the externalTrafficPolicy to Local.
+
+
+### Language, grammar and tone
+
+- Documentation should be written in English.
+- Prefer an active voice and present tense when possible.
+  - Active voice is when the subject of the sentence performs the action.
+    Whereas with passive voice the subject receives the action. Writing with an
+    active voice in mind easily conveys to the reader who or what is performing
+    the action.
+  - **Good example:** Updating the Deployment triggers a new ReplicaSet to be
+    created.
+  - **Bad example:** A ReplicaSet is created by updating the Deployment.
+- Use simple and direct language.
+  - Avoid using unnecessary or extra language. Be straightforward and direct.
+  - **Good example:** Wait for the Pod to start.
+  - **Bad example:** Please be patient and wait for the Pod to start.
+- Use gender-neutral language.
+  - Avoid gendered pronouns preferring the [singular "they"][singular-they]
+    unless referring to the person's by their preferred gender. For further
+    information on the subject, see [Microsoft's guide to bias-free communication]
+    and [Wikipedia's entry for the Singular they].
+  - **Good example:** chair or moderator
+  - **Bad example:** chairman
+- Avoid personal pronouns ("I," "we," "us," "our," and "ours").
+  - In most cases personal pronouns should be avoided as they can lead to
+    confusion regarding who they are referring to. 
+  - **Good example:** The release-team shepherded the successful release of 1.13.
+  - **Bad example:** We shepherded the successful release of 1.13.
+- Address the reader as "you" instead of "we".
+  - Addressing the reader directly using "you" clearly denotes the target.
+    There is no confusion as there would be with "we" or "us".
+  - **Good example:** You will create a new cluster with kubeadm.
+  - **Bad example:** We will create a new cluster with kubeadm.
+- Do not use Latin phrases.
+  - [Latin phrases] can make it difficult for readers not familiar with them to
+    grasp their meaning. 
+  - Some useful alternatives include:
+
+    | Latin Phrase | Alternative |
+    |:------------:|:-----------:|
+    |     e.g.     | for example |
+    |    et al.    |  and others |
+    |     i.e.     |   that is   |
+    |     via      |    using    |
+
+  - **Good example:** For example Deployments, ReplicaSets...
+  - **Bad example:** e.g. Deployments, ReplicaSets...
+- Avoid jargons and idioms.
+  - Jargon and idioms tend to rely on regional or tribal knowledge. They make
+    it difficult to understand for both newcomers and those whose native
+    language is something other than English. They should be avoided when
+    possible.
+  - **Good example:** Internally, the kube-apiserver...
+  - **Bad example:** Under the hood the kube-apiserver...
+  - **Good example:** We will start the project in early 2019.
+  - **Bad example:** We will kick off the initiative in 2019.
+- If using an abbreviation, spell it out the first time it is used in the
+  document unless it is commonly known. (example: TCP/IP)
+  - Abbreviations in this context applies to abbreviations, acronyms and
+    initialisms.
+  - **Good example:** A _CustomResourceDefinition_ (CRD) extends the Kubernetes
+    API.
+  - **Bad example:** A CRD extends the Kubernetes API.
+
+
+### Moving a Document
+
+- Use `[git-mv]` to move documents.
+  - `git-mv` will safely move/rename a file, directory, or symlink and
+    automatically update the git index.
+  - **Good example:** `git mv /old/mydoc.md /new/mydoc.md`
+  - **Bad example:** `mv /old/mydoc.md /new/mydoc.md`
+- Commit moved documents separately from any other changes.
+  - A separate commit clearly preserves the history of the relocated documents
+    and makes it easier to review.
+- When a document has moved, leave a tombstone file with a removal date in its
+  place.
+  - Tombstones function as a pointer and give users a time to update their own
+    documentation and bookmarks. Their usefulness is time-bounded and should be
+    removed when they would logically no longer serve their purpose.
+    ```markdown
+    This file has moved to https://git.k8s.io/community/contributors/guide/README.md.
+
+    This file is a placeholder to preserve links.  Please remove after 2019-03-10 or the release of kubernetes 1.10, whichever comes first.
+    ```
+
+
+### Punctuation
+
+- Do not use punctuation in headings.
+- End full sentences with a period.
+  - **Exception:** When a sentence ends with a URL or if the text would be
+    unclear if the period is a part of the previous object or word.
+- Add a single space after a period when beginning a new sentence.
+- Avoid usage of exclamation points unless they are a part of a code example.
+- Use an [Oxford comma] when a list contains 3 or more elements.
+  - **Good example:** Deployments, ReplicaSets, and DaemonSets.
+  - **Bad example:** Deployments, ReplicaSets and DaemonSets.
+
+
+### Quotation
+
+- Use double-quotation marks (`" "`) over single-quotation marks (`' '`).
+  - **Exception:** In code snippets where quotation marks have specific meaning.
+  - **Exception:** When nesting quotation marks inside another set of quotation
+    marks.
+- Punctuation should be outside of quotation marks following the international
+  (British) standard.
+
+
+---
+
+
+## Markdown formatting
+
+### Code blocks
+
+- When possible, reference the language at the beginning of a Code Block.
+  - The two markdown renderers used by the Kubernetes community
+    ([GitHub][gh-code-hl-list] and [Hugo][hugo-code-hl-list]) support code
+    highlighting. This can be enabled by supplying the name of the language
+    after the three back-ticks (`` ``` ``) at the start of a code block.
+  - **Good example:**
+    `````
+    ```go
+    import (
+      "fmt"
+      ...
+    )
+    ```
+    `````
+  - **Bad example:**
+    `````
+    ```
+    import (
+      "fmt"
+      ...
+    )
+    ```
+    `````
+- When a code block is used to reference a shell, do not include the command
+  prompt (`$`)
+  - When a code block is referencing a shell, it is implied that it is a
+    command prompt. The exception to this is when a code block is being used
+    for raw shell output such as debug logs. 
+  - **Good example:**
+    ```
+    kubectl get pods -o wide
+    ```
+  - **Bad example:**
+    ```
+    $ kubectl get pods -o wide
+    ```
+- Separate commands from output.
+  - Separating the command from the output makes both the command and output
+    more generally readable.
+  - **Good example:**
+    ```
+    kubectl get pods
+    ```
+    ```
+    NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
+    nginx    1/1       Running   0          13s    10.200.0.4   worker0
+    ```
+  - **Bad example:**
+    ```
+    kubectl get pods
+    NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
+    nginx    1/1       Running   0          13s    10.200.0.4   worker0
+    ```
+
+
+### Emphasis
+
+Markdown has multiple ways of indicating each type of emphasis. Adhering to a
+standard across documentation improves supportability.
+
+- Use two asterisks (`**`) for **Bold** text.
+  - **Good example:** `This is **bold** text.`
+  - **Bad example:** `This should not be used for __bold__.`
+- Use an underscore (`_`) for _Italics_.
+  - **Good example:** This is _italics_.`
+  - **Bad example:**  This should not be used for *italics*.`
+- Use two tildes (`~~`) for ~~Strikethrough~~.
+  - **Good example:** `This is ~~strikethrough~~`
+  - **Bad example:** `This should not be used for ~strikethrough~.`
+
+
+### Headings
+
+ Adhering to a standard across documentation improves both readability and
+ overall supportability across multiple documents.
+
+- Use a single `H1` (`#`) Heading per document.
+  - **Exception:** `H1` may be used multiple times in the same document when
+    there is a large content shift or "chapter" change.
+- Follow the Header hierarchy of `H2` > `H3` > `H4` > `H5` > `H6`.
+- Use sentence-style capitalization in titles (first word and proper nouns).
+- Avoid using special characters.
+- Leave exactly 1 new line after a heading.
+- Avoid using links in headings.
+
+
+### Horizontal rules
+
+Markdown has multiple ways of indicating a horizontal rule. Adhering to a
+standard across documentation improves supportability.
+
+- Use three dashes (`---`) to denote a horizontal rule.
+  - **Good example:** `---`
+  - **Bad example:** `===`
+- Use a horizontal rule (`---`) to logically separate large sections.
+
+
+### Line length
+
+- Prefer an 80 character line limit.
+  - There is no specific general best practice for Markdown line length. The
+    commonly used 80 character guideline is preferable for general text review
+    and editing.
+
+
+### Links
+
+Markdown provides two primary methods to link to content: inline links and
+relative links. However, how and what they're being linked to can vary widely. 
+
+- Prefer using reference style links over inline style links.
+  - Reference links are shorter and easier to read. They have the added benefit
+    of being reusable throughout the entire document. 
+  - The link itself should be at the bottom of the document. If the document is
+    large or covers many topics, place the link at the end of the logical
+    chapter or section.
+  - **Example:**
+    ```
+    See the [Code of Conduct] for more information.
+
+    [code of conduct]: https://git.k8s.io/community/code-of-conduct.md
+    ```
+  - **Example:**
+    ```
+    See the [Code of Conduct][coc] for more information.
+
+    [coc]: https://git.k8s.io/community/code-of-conduct.md
+    ```
+- When linking within the same directory, use a relative link.
+  - Links to files within the same directory are short and readable already.
+    They do not warrant expanding the full path.
+  - When the file is referenced multiple times within the same document,
+    consider using a reference link for a quicker shorthand reference.
+  - **Example:**
+    ```
+    See the [Code of Conduct](code-of-conduct.md) for more information
+    ```
+  - **Example:**
+    ```
+    See the [Code of Conduct][coc] for more information
+
+    [coc]: code-of-conduct.md
+    ```
+- When linking to a document outside of the current directory, use the absolute
+  path from the root of the repository.
+  - Using the absolute path ensures that if the source document is relocated,
+    the link to the target or destination document will remain intact and not
+    have to be updated.
+  - **Example:**
+    ```
+    See the [Coding Convention] doc for more information.
+
+    [Coding Convention]: /contributors/guide/coding-conventions.md
+    ```
+- When linking to a file in another Kubernetes github repository, use the
+  `k8s.io` url shortener.
+  - The shorthand version will auto-expand linking to documents within the
+    master branch and can be used for multiple purposes. 
+
+    |      Short URL      |            Expanded URL            |
+    |:-------------------:|:----------------------------------:|
+    |  https://git.k8s.io |    https://github.com/kubernetes   |
+    | https://sigs.k8s.io | https://github.com/kubernetes-sigs |
+
+  - **Example:**
+    ```
+    The super cool [prow tool] resides in the test-infra repo under the kubernetes organization
+
+    [prow tool]: https://git.k8s.io/test-infra/prow/README.md
+    ```
+
+
+### Lists
+
+ Adhering to a standard across documentation improves both readability and
+ overall supportability across multiple documents.
+
+- Capitalize the first character of each entry unless the item is explicitly
+  case sensitive.
+- End each entry with a period if it is a sentence or phrase.
+- Use a colon (`:`) to separate a list item name from the explanatory text.
+- Leave a blank line after each list.
+- Use `-` for unordered lists.
+- For ordered lists a repeating `1.` may be used.
+- When inserting a code block into an ordered list, indent (space) an additional
+  two times.
+
+
+### Metadata
+
+- If the document is intended to be surfaced on the Contributor Site; include a
+  yaml metadata header at the beginning of the document.
+  - If the document is to be added to the Contributor Site, adding metadata
+    at the beginning of the document will improve the overall presentation of
+    the information. This metadata is similar to the metadata used in the
+    KEP process and is often referred to as _Frontmatter_ in common static
+    site generators such as [Jekyll] and [Hugo].
+  - The metadata header is a yaml block between two sets of `---`.
+  - **Example:**
+    ```
+    ---
+    title: Super Awesome Doc
+    ---
+    ```
+- Metadata must include the `title` attribute.
+  - `title` will be used as the title of the document when rendered with
+    [Hugo].
+
+
+### Tables
+
+- Use tables for structured information.
+  - **Example:**
+    ```
+    |    Column 1    |    Column 2    |    Column 3    |
+    |:--------------:|:--------------:|:--------------:|
+    |     test 1     |     test 2     |     test 3     |
+    | another test 1 | another test 2 | another test 3 |
+    ```
+- Tables do not need to adhere to the suggested line length.
+  - Markdown tables have an inherently longer line length, and cannot be
+    line wrapped. 
+- Avoid long inline links.
+  - Long inline links can make it difficult to work with markdown tables.
+    Prefer to use reference style links instead.
+- Do not use excessively wide tables.
+  - Large wide tables do not render well. Try to break the information down
+    into something more easily presentable.
+
+
+## Attribution
+
+This style guide is heavily influenced by the great work from the content
+management teams from [SIG-Docs], [Gitlab], [Google], and [Microsoft]. Without
+their previous efforts this guide would not be nearly as concise as it should.
+
+[community repository]: https://git.k8s.io/community
+[Kubernetes documentation style-guide]: https://kubernetes.io/docs/contribute/style/style-guide/
+[SIG Google groups]: /sig-list.md
+[ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
+[kubernetes icon set]: /icons
+[API naming convention]: /contributors/devel/api-conventions.md#naming-conventions
+[singular-they]: https://en.wikipedia.org/wiki/Singular_they
+[Microsoft's guide to bias-free communication]: https://docs.microsoft.com/en-us/style-guide/bias-free-communication
+[Wikipedia's entry for the Singular they]: https://en.wikipedia.org/wiki/Singular_they
+[Latin phrases]: https://en.wikipedia.org/wiki/List_of_Latin_abbreviations
+[Oxford comma]: https://www.grammarly.com/blog/what-is-the-oxford-comma-and-why-do-people-care-so-much-about-it/
+[gh-code-hl-list]: https://github.com/github/linguist/blob/master/lib/linguist/languages.yml
+[hugo-code-hl-list]: http://www.rubycoloredglasses.com/2013/04/languages-supported-by-github-flavored-markdown/
+[git-mv]: https://git-scm.com/docs/git-mv
+[jekyll]: https://jekyllrb.com/
+[hugo]: https://gohugo.io/
+[gitlab]: https://docs.gitlab.com/ee/development/documentation/styleguide.html
+[google]: https://developers.google.com/style/
+[microsoft]: https://docs.microsoft.com/en-us/style-guide/welcome/
+[sig-docs]: https://kubernetes.io/docs/contribute/style/style-guide/