Fix contribution guide about adding code samples

We have consolidated all YAML examples into `content/en/examples`
directory. This PR updates the contribution guide so that people know
where to put their sample YAML files when adding/changing topics.

content/en/docs/home/contribute/write-new-topic.md

@@ -91,39 +91,46 @@ Here's an example of an entry in /_data/tasks.yaml:
 
 ## Including code from another file
 
-To include a code file in your topic, place the code file in the Kubernetes
-documentation repository, preferably in the same directory as your topic
-file. In your topic file, use the `include` tag:
+If you want to include some code in your topic, you can do one of the followings:
 
-<pre>&#123;% include code.html language="&lt;LEXERVALUE&gt;" file="&lt;RELATIVEPATH&gt;" ghlink="/&lt;PATHFROMROOT&gt;" %&#125;</pre>
+- Embed the code in your topic directly using the markdown code block syntax.
+  When the provided code is not generic enough for users to try out, or the code
+  is an incomplete example because its purpose is to highlight a portion of a
+  large file otherwise, this is the recommended practice.
+- Create a new, complete sample file and then reference the sample from your topic.
+  This is the preferred way of including sample YAML files when the sample is
+  generic, reusable, and you want the readers to try it out by themselves.
 
-where:
+When adding a new standalone sample file (e.g. a YAML file), place the code in
+one of the `<LANG>/examples/` subdirectories where `<LANG>` is the language for
+the topic. In your topic file, use the `codenew` shortcode:
 
-* `<LEXERVALUE>` is the language in which the file was written. This must be
-[a value supported by Rouge](https://github.com/jneen/rouge/wiki/list-of-supported-languages-and-lexers).
-* `<RELATIVEPATH>` is the path to the file you're including, relative to the current file, for example, `local-volume.yaml`.
-* `<PATHFROMROOT>` is the path to the file relative to root, for example, `docs/tutorials/stateful-application/mysql-wordpress-persistent-volume/local-volumes.yaml`.
+<pre>&#123;&#123;&lt; codenew file="&lt;RELPATH&gt;/my-example-yaml&gt;" &gt;&#125;&#125;</pre>
 
-Here's an example of using the `include` tag:
+where `<RELPATH>` is the path to the file you're including, relative to the
+`examples` directory. For example, the following short code references a YAML
+file located at `content/en/examples/pods/storage/gce-volume.yaml`.
 
-<pre>&#123;% include code.html language="yaml" file="gce-volume.yaml" ghlink="/docs/tutorials/stateful-application/gce-volume.yaml" %&#125;</pre>
+<pre>&#123;&#123;&lt; codenew file="pods/storage/gce-volume.yaml" &gt;&#125;&#125;</pre>
 
 ## Showing how to create an API object from a configuration file
 
 If you need to show the reader how to create an API object based on a
-configuration file, place the configuration file in the Kubernetes documentation
-repository, preferably in the same directory as your topic file.
+configuration file, place the configuration file in one of the subdirectories
+under `<LANG>/examples`.
 
 In your topic, show this command:
 
-    kubectl create -f https://k8s.io/<PATHFROMROOT>
+```
+kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml
+```
 
-where `<PATHFROMROOT>` is the path to the configuration file relative to root,
-for example, `docs/tutorials/stateful-application/mysql-wordpress-persistent-volume/local-volumes.yaml`.
-
-Here's an example of a command that creates an API object from a configuration file:
-
-    kubectl create -f https://k8s.io/docs/tutorials/stateful-application/mysql-wordpress-persistent-volume/local-volumes.yaml
+{{< note >}}
+**NOTE**: When adding new YAML files to the `<LANG>/examples` directory, make
+sure the file is also included into the `<LANG>/examples_test.go` file. The
+Travis CI for the Website automatically runs this test case when PRs are
+submitted to ensure all examples pass the tests.
+{{< /note >}}
 
 For an example of a topic that uses this technique, see
 [Running a Single-Instance Stateful Application](/docs/tutorials/stateful-application/run-stateful-application/).