SPARK-3642. Document the nuances of shared variables.

@sryza Actually this is not true....

scala> val acc = sc.accumulator(0)

scala> val data = sc.parallelize(List(1, 2, 3))
data: org.apache.spark.rdd.RDD[Int] = ParallelCollectionRDD[0] at parallelize at <console>:12

scala> val a = data.map(x => acc += 1)

scala> a.count

scala> acc.value
res5: Int = 3

scala> a.count
scala> acc.value
res7: Int = 6

I will resubmit https://github.com/apache/spark/pull/228 tonight or tomorrow,