Updates to the pants essentials tech talk based on another dry-run.

Reviewed at https://rbcommons.com/s/twitter/r/1484/

src/python/pants/docs/.gitignore

@@ -2,3 +2,7 @@
 _build
 build_dictionary.rst
 goals_reference.rst
+
+# Ignore pants essentials CDK output
+pants_essentials_techtalk.html
+pants_essentials_techtalk__*.png

src/python/pants/docs/pants_essentials_techtalk.asc

@@ -10,9 +10,9 @@ Today we're learning the _essentials_. Practical knowledge that will help you _g
 
 ****
 * press 'S' to show/hide these speaker notes
-* We assume you use Pants, but don't understand what you're doing. (Why are y'all here?)
+* We assume you use Pants, but don't necessarily understand what you're doing.
+* So we'll ask -- why are you here, what specifically do you want to know about?
 * Quick review of what build systems do, and what they don't do.
-* Demo of using pants.
 ****
 
 
@@ -34,9 +34,12 @@ Today we're learning the _essentials_. Practical knowledge that will help you _g
 
 * You Tell Pants: "apply *these* goals to *those* targets"
 
-* Pants plans: "download, compile, build, test"
+* Pants analyzes: examines your target & its dependencies
+
+* Pants plans: "download jars, generate code, compile, test"
+
+* Pants invokes: Downloaders, Generators, Compilers, testers, ...
 
-* Pants invokes: Compilers, testers, ...
 
 == Targets - "nouns" of the build
 
@@ -63,6 +66,7 @@ include::goals_graph.dot['Example Goals Graph']
 (abridged visualization of `./pants goal test`)
 
 ****
+* Walk though the diagram, starting from test, to the left.
 * You give Pants one or more goals, like `test`
 * Within a goal might be a few tasks. E.g., `test` has `junit`, `pytest`.
 * Many tasks are no-ops. E.g., `pytest` for java code.
@@ -73,8 +77,7 @@ include::goals_graph.dot['Example Goals Graph']
 == Let's Walk Through a Build
 
 [source,bash]
-  ./pants goal test
-  examples/tests/java/com/pants/examples/hello/greet
+  ./pants goal test src/java/shapes/polygons/octagon
 
 ["graphviz"]
 ----
@@ -87,6 +90,7 @@ include::targets_graph_test.dot['Targets Graph']
 ----
 
 ****
+* PANTS WORKS THE GRAPH FROM BOTTOM -> UP
 * `gen` sees our thrift, generates Java.
 * `resolve` fetches jars from maven repo
 * `compile` compiles our source, plus generated from thrift
@@ -96,7 +100,7 @@ include::targets_graph_test.dot['Targets Graph']
 == Anatomy of a Command Line
 
 ----
-./pants goal goalname [flags] [goalname ...] [flags] path/to/target/foo:foo
+./pants goal goalname [flags] path/to/target/foo
 ----
 
 ----
@@ -114,7 +118,7 @@ include::targets_graph_test.dot['Targets Graph']
 
 == Targets
 
-Here's a simple library target. You might find this in +src/java/com/twitter/foo/BUILD+.
+Here's a simple library target. You might find this in +src/java/com/mycom/foo/BUILD+.
 
 [source,python]
 ----
@@ -140,7 +144,7 @@ More than one way to say it
 //path/to/foo:foo
 path/to/foo:foo
 path/to/foo  (target with same name as dir)
-:foo  (in def'n of 'bar' in same BUILD file)
+:foo  (used in another target in same BUILD file)
 ----
 
 *Command Line-only* conveniences:
@@ -163,7 +167,7 @@ When developing on the JVM, the following target types are most frequently used:
 
 * +java_library+ - A collection of Java code.
 * +scala_library+ - A collection of Scala code.
-* +junit_tests+ - Tests a JVM library with JUnit.
+* +junit_tests+ - Tests a +java_library+/+scala_library+ with JUnit.
 * +jar_library+ - Jar(s) from a maven repo
 * +jvm_binary+ - A JVM binary optionally identifying a launcher main class.
 * +jvm_app+ - A jvm app package consisting of a binary plus additional bundles of files.
@@ -172,16 +176,16 @@ When developing on the JVM, the following target types are most frequently used:
 * jvm_app/jvm_binary is legacy wart. Really, should have one target type w/optional bundles
 ****
 
-== Every Day Commands
-
-* +./pants goal test+
-* +./pants goal bundle+
-
 == IntelliJ
 
+* First-class pants support within IntelliJ (similar to maven, gradle, etc.)
 * Get the plugin: https://github.com/pantsbuild/intellij-pants-plugin
 * Create projects based on BUILD files
 
+****
+* Most developers use pants from the command line, but for those who like a GUI...
+****
+
 == Pants Patterns
 
 * 3rdparty Dependencies
@@ -195,26 +199,9 @@ When developing on the JVM, the following target types are most frequently used:
 together to best achieve a specific outcome.
 ****
 
-== 3rdparty Dependencies
-
-You probably use code from outside the repo.
-
-----
-# 3rdparty/jvm/org/elasticsearch:elasticsearch
-jar_library(name='elasticsearch',
-  jars=[
-    jar(org='org.elasticsearch', name='elasticsearch', rev='1.1.0')
-  ]
-)
-----
-
-****
-* Recommended target addresses 3rdparty/$LANG/$ORG:$NAME
-* All internal sources use same external library version. Catch many diamond dependency issues.
-* Aids discoverability, `git log` "detective work"
-* Per-language conventions within language subdir. Use JVM for Java/Scala.
-****
+== 3rdparty!
 
+You probably use code from outside the repo. But if you're not careful, external dependencies can cause problems...
 
 == Diamond Dependencies
 
@@ -227,7 +214,7 @@ digraph G {
   java_library_b [label="bar"];
   java_library_c [label="baz"];
   java_library_a -> java_library_b -> guava_12;
-  java_library_a -> java_library_c -> guava_14;
+  java_library_a -> java_library_c -> guava_16;
 }
 ----
 
@@ -238,9 +225,9 @@ digraph G {
 * Instead, use this convention: Define each external jar once. Use this internal dependency in projects that need it.
 ****
 
-== Diamond Dependencies
+== Fix A Diamond Dependency
 
-Point at same version
+Point at same version, preventing the diamond from happening in the first place
 
 ["graphviz"]
 ----
@@ -259,6 +246,27 @@ digraph G {
 * Ha ha, but look out for transitives!
 ****
 
+== 3rdparty Dependencies
+
+Generalize this as "the 3rdparty pattern". By convention, create targets for all external dependencies, in a shared directory:
+
+----
+# 3rdparty/jvm/com/google:guava
+jar_library(name='guava',
+  jars=[
+    jar(org='com.google', name='guava', rev='16.0.1')
+  ]
+)
+----
+
+****
+* The solution to the diamond dependency problem! (well, not totally)
+* Recommended target addresses 3rdparty/$LANG/$ORG:$NAME
+* All internal sources use same external library version. Catch many diamond dependency issues.
+* Aids discoverability, `git log` "detective work"
+* Per-language conventions within language subdir. Use JVM for Java/Scala.
+****
+
 == 1:1:1 Rule
 
 * 1 Directory
@@ -268,6 +276,9 @@ digraph G {
 ****
 * Not a law, this "rule" is a rule of thumb
 * fine-grained BUILD targets
+* This is a way to avoid using rglobs(), which is an easy way to bundle lots of code into a target...
+* ... that maybe isn't needed by all dependees of said target.
+* also transitively pull in less dependencies
 ****
 
 == Pants and Thrift
@@ -279,12 +290,12 @@ Inside Twitter, there's a helper function to avoid boilerplate (mult langs, Fina
 
 include::pants_essentials_thrift.asc[]
 
-== Deploy Bundles, jar-only case
+== Deploying a Bundle
 
 Want to upload something runnable to a server? Generate a bundle:
 
 ----
-jvm_binary(name='foo-bin', dependencies=['src/java/com/twitter/foo'], ... )
+jvm_binary(name='foo-bin', dependencies=['src/java/com/mycom/foo'], ... )
 
 jvm_app(name='foo-app', binary=':foo-bin',
   bundles=[bundle(relative_to='common').add(rglobs('common/*')),] ... )
@@ -294,6 +305,8 @@ jvm_app(name='foo-app', binary=':foo-bin',
 ./pants goal bundle foo:foo-app --bundle-archive=zip
 ----
 
+Pants will produce +dist/foo-app.zip+ for you.
+
 ****
 * `relative_to` means that `common/foo.ini` gets bundled at `./foo.ini`
 * The raw bundle and zip are created in the +dist+ dir.
@@ -304,6 +317,7 @@ jvm_app(name='foo-app', binary=':foo-bin',
 * Goals online help: +
   +./pants goal goals+ +
   +./pants goal foo -h+
+  +./pants goal -e foo+ (shows all goals run before foo)
 * Target types (and other `BUILD` things) +
   +./pants goal targets+ +
   +./pants goal targets --targets-details=foo+
@@ -314,3 +328,7 @@ jvm_app(name='foo-app', binary=':foo-bin',
   http://pantsbuild.github.io/goals_reference.html
 * Right now: +
   *Questions?*
+
+****
+* The point of explain is that it gives a list of goals, any can get a '+-h+'
+****

src/python/pants/docs/pants_essentials_thrift.asc

@@ -1,7 +1,7 @@
 ----
-java_thrift_library(name='mybird-scala',
+java_thrift_library(name='myproj-scala',
   sources=globs('*.thrift'),
-  dependencies=['src/thrift/included:includedbird-scala',],
+  dependencies=['src/thrift/included:includedproj-scala',],
   compiler='scrooge',
   language='scala',
   rpc_style='finagle',
@@ -10,4 +10,4 @@ java_thrift_library(name='mybird-scala',
 
 ****
 * A `scala_library` can depend on this, import its code
-****
+****