(Side note: This man page needs some serious rewriting but let's start small.)

Under "--cpu-shares":

"For example, consider three containers, [where] one has a cpu-share of 1024"
                                          ^^^^^ add this word

Also, in that above sentence (and sentences further down), the phrase used is "cpu-share" (singular), while the actual option is "--cpu-shares" (plural). For consistency, either use the generic phrase "CPU share" (which is perfectly valid), or use the option name "cpu-shares" -- don't use this weird in-between reference of "cpu-share".

More to the point, that entire section explaining --cpu-shares seems confusing. One reads:

"To modify the proportion from the default of 1024 ..."

But what does a default value of 1024 *represent*? The reader is not told. Only reading further does it become obvious(?) that 1024 represents the maximum CPU share that can be allocated (if that's in fact what it means; I'm just assuming I'm reading this correctly.)

  Now, given the example shown there, it would be useful to present a table as is done for the multi-core example even further down -- a table would be tremendously useful for clarifying what is happening (both for the initial three-container scenario, and for what happens after you add a fourth container).

  Next, while "docker build --help" prints the following snippet:

  --cpuset-cpus=        CPUs in which to allow execution (0-3, 0,1)
  --cpuset-mems=        MEMs in which to allow execution (0-3, 0,1)

the man page reads:

       --cpuset-cpus=CPUSET-CPUS
         CPUs in which to allow execution (0-3, 0,1).

       --cpuset-mems=CPUSET-MEMS
         Memory nodes (MEMs) in which to allow execution (-1-3, 0,1). 
         Only effective on NUMA systems.                  ^^^^ ???

What means "-1-3"? Is that deliberate, or a typo?

  Finally (for now), under EXAMPLES, one reads:

"It  is  also  a  good practice to add the files required for the image to the sub-directory. These files will then be specified with the COPY or ADD instructions in the Dockerfile."

  In what way is this just "good practice" as opposed to being *required*? How else will you have access to those files unless you add them to the context for this build? Or am I missing something here?

  And I would reword that second sentence to be much more explicit as to what is going on:

"These files will then be selected for inclusion in the new image with the COPY or ADD instructions in the Dockerfile."

  That's all for now.