diff --git a/hadoop-yarn-project/CHANGES.txt b/hadoop-yarn-project/CHANGES.txt
index d7f6932484..8a60a1519a 100644
--- a/hadoop-yarn-project/CHANGES.txt
+++ b/hadoop-yarn-project/CHANGES.txt
@@ -57,6 +57,8 @@ Release 2.3.0 - UNRELEASED
     YARN-465. fix coverage org.apache.hadoop.yarn.server.webproxy (Aleksey
     Gorshkov and Andrey Klochkov via jlowe)
 
+    YARN-976. Document the meaning of a virtual core. (Sandy Ryza)
+
   OPTIMIZATIONS
 
   BUG FIXES
diff --git a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Resource.java b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Resource.java
index 5a85e7ce34..88b57f1c68 100644
--- a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Resource.java
+++ b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Resource.java
@@ -28,7 +28,18 @@ import org.apache.hadoop.yarn.util.Records;
  * <p><code>Resource</code> models a set of computer resources in the 
  * cluster.</p>
  * 
- * <p>Currrently it only models <em>memory</em>.</p>
+ * <p>Currently it models both <em>memory</em> and <em>CPU</em>.</p>
+ * 
+ * <p>The unit for memory is megabytes. CPU is modeled with virtual cores
+ * (vcores), a unit for expressing parallelism. A node's capacity should
+ * be configured with virtual cores equal to its number of physical cores. A
+ * container should be requested with the number of cores it can saturate, i.e.
+ * the average number of threads it expects to have runnable at a time.</p>
+ * 
+ * <p>Virtual cores take integer values and thus currently CPU-scheduling is
+ * very coarse.  A complementary axis for CPU requests that represents processing
+ * power will likely be added in the future to enable finer-grained resource
+ * configuration.</p>
  * 
  * <p>Typically, applications request <code>Resource</code> of suitable
  * capability to run their component tasks.</p>
@@ -69,11 +80,10 @@ public abstract class Resource implements Comparable<Resource> {
   /**
    * Get <em>number of virtual cpu cores</em> of the resource.
    * 
-   * We refer to <em>virtual cores</em> to clarify that these represent
-   * <em>normalized</em> cores which may have a m:n relationship w.r.t
-   * physical cores available on the compute nodes. Furthermore, they also 
-   * represent <em>idealized</em> cores since the cluster might be composed
-   * of <em>heterogenous</em> nodes.
+   * Virtual cores are a unit for expressing CPU parallelism. A node's capacity
+   * should be configured with virtual cores equal to its number of physical cores.
+   * A container should be requested with the number of cores it can saturate, i.e.
+   * the average number of threads it expects to have runnable at a time.
    *   
    * @return <em>num of virtual cpu cores</em> of the resource
    */
@@ -84,12 +94,11 @@ public abstract class Resource implements Comparable<Resource> {
   /**
    * Set <em>number of virtual cpu cores</em> of the resource.
    * 
-   * We refer to <em>virtual cores</em> to clarify that these represent
-   * <em>normalized</em> cores which may have a m:n relationship w.r.t
-   * physical cores available on the compute nodes. Furthermore, they also 
-   * represent <em>idealized</em> cores since the cluster might be composed
-   * of <em>heterogenous</em> nodes.
-   *   
+   * Virtual cores are a unit for expressing CPU parallelism. A node's capacity
+   * should be configured with virtual cores equal to its number of physical cores.
+   * A container should be requested with the number of cores it can saturate, i.e.
+   * the average number of threads it expects to have runnable at a time.
+   *    
    * @param vCores <em>number of virtual cpu cores</em> of the resource
    */
   @Public