Mailing-List: contact commits-help@tinkerpop.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@tinkerpop.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: spmallette@apache.org
To: commits@tinkerpop.apache.org
Date: Thu, 10 Aug 2017 16:14:54 -0000
Message-Id: <8f17ae802e044db6b2bbae1e72290d08@git.apache.org>
In-Reply-To: <d5359e4ee6f04478b48bf7e436003ad2@git.apache.org>
References: <d5359e4ee6f04478b48bf7e436003ad2@git.apache.org>
Subject: [4/5] tinkerpop git commit: Minor additions/improvements to the
 Getting Started tutorial CTR
archived-at: Thu, 10 Aug 2017 16:14:53 -0000

Minor additions/improvements to the Getting Started tutorial CTR


Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/23caf367
Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/23caf367
Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/23caf367

Branch: refs/heads/master
Commit: 23caf3670170664f47fc8756ddf1a0031cdff55b
Parents: 6a3fc39
Author: Stephen Mallette <spmva@genoprime.com>
Authored: Thu Aug 10 12:05:52 2017 -0400
Committer: Stephen Mallette <spmva@genoprime.com>
Committed: Thu Aug 10 12:14:13 2017 -0400

----------------------------------------------------------------------
 .../tutorials/getting-started/index.asciidoc    | 43 ++++++++++++++------
 1 file changed, 30 insertions(+), 13 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/23caf367/docs/src/tutorials/getting-started/index.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/tutorials/getting-started/index.asciidoc b/docs/src/tutorials/getting-started/index.asciidoc
index dfdf349..bc906cb 100644
--- a/docs/src/tutorials/getting-started/index.asciidoc
+++ b/docs/src/tutorials/getting-started/index.asciidoc
@@ -90,15 +90,21 @@ TIP: TinkerGraph is not just a toy for beginners. It is useful in analyzing subg
 working with a small static graph that doesn't change much, writing unit tests and other use cases where the graph
 can fit in memory.
 
-TIP: Resist the temptation to "get started" with more complex databases like link:http://thinkaurelius.github.io/titan/[Titan]
-or to delve into how to get link:http://tinkerpop.apache.org/docs/x.y.z/reference/#gremlin-server[Gremlin Server]
+TIP: For purposes of "getting started", resist the temptation to dig into more complex databases that have lots of
+configuration options or to delve into how to get link:http://tinkerpop.apache.org/docs/x.y.z/reference/#gremlin-server[Gremlin Server]
 working properly. Focusing on the basics, presented in this guide, builds a good foundation for all the other things
 TinkerPop offers.
 
-To make your process even easier, start with one of TinkerPop's "toy" graphs. These are "small" graphs designed to
-provide a quick start into querying. It is good to get familiar with them, as almost all TinkerPop documentation is based
-on them and when you need help and have to come to the link:http://groups.google.com/group/gremlin-users[mailing list],
-a failing example put in the context of the toy graphs can usually get you a fast answer to your problem.
+To make your learning process even easier, start with one of TinkerPop's "toy" graphs. These are "small" graphs
+designed to provide a quick start into querying. It is good to get familiar with them, as almost all TinkerPop
+documentation is based on them and when you need help and have to come to the
+link:http://groups.google.com/group/gremlin-users[mailing list], a failing example put in the context of the toy graphs
+can usually get you a fast answer to your problem.
+
+TIP: When asking questions on the mailing list or StackOverflow about Gremlin, it's is always helpful to include a
+sample graph so that those attempting to answer your question understand exactly what kind of graph you have and can
+focus their energies on a good answer rather than trying to build sample data themselves. The sample graph should just
+be a simple Gremlin script that can be cut and paste into a Gremlin Console session.
 
 For your first graph, use the "Modern" graph which looks like this:
 
@@ -146,12 +152,13 @@ the results of the `g.V()` query.  Rather, that statement assigns an `Iterator`
 you would then need to iterate through `x`. This understanding is *important* because in the context of the console
 typing `g.V()` instantly returns a value. The console does some magic for you by noticing that `g.V()` returns
 an `Iterator` and then automatically iterates the results. In short, when writing Gremlin outside of the console
-always remember that you must iterate your `Traversal` manually in some way for it to do anything.
+always remember that you must iterate your `Traversal` manually in some way for it to do anything. The concept of
+"iterating your traversal" is described further in link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/the-gremlin-console/[The Gremlin Console Tutorial].
 
 In this first five minutes with Gremlin, you've gotten the Gremlin Console installed, instantiated a `Graph` and
 `TraversalSource`, wrote some traversals and hopefully learned something about TinkerPop in general. You've only
 scratched the surface of what there is to know, but those accomplishments will help enable your understanding of the
-detailed sections to come.
+more detailed sections to come.
 
 The Next Fifteen Minutes
 ------------------------
@@ -367,9 +374,15 @@ are the people that marko develops software with?" To do that, we should first p
 the previous query.  He was standing on the "software" vertex. To find out who "created" that "software", we need to
 have Gremlin traverse back _in_ along the "created" edges to find the "person" vertices tied to it.
 
+TIP: The nature of Gremlin leads to long lines of code. Readability can be greatly improved by using line spacing and
+indentation. See the link:http://tinkerpop.apache.org/docs/x.y.z/recipes/#style-guide[Style Guide] for recommendations
+on what well formatted Gremlin should look like.
+
 [gremlin-groovy,modern]
 ----
-g.V().has('name','marko').out('created').in('created').values('name')
+g.V().has('name','marko').
+  out('created').in('created').
+  values('name')
 ----
 
 So that's nice, we can see that "peter", "josh" and "marko" are both responsible for creating "lop". Of course, we already
@@ -378,7 +391,10 @@ know about the involvement of "marko" and it seems strange to say that "marko" c
 
 [gremlin-groovy,modern]
 ----
-g.V().has('name','marko').as('exclude').out('created').in('created').where(neq('exclude')).values('name')
+g.V().has('name','marko').as('exclude').
+  out('created').in('created').
+  where(neq('exclude')).
+  values('name')
 ----
 
 We made two additions to the traversal to make it exclude "marko" from the results. First, we added the
@@ -397,7 +413,8 @@ You will find many uses of `as()`. Here it is in combination with link:http://ti
 
 [gremlin-groovy,modern]
 ----
-g.V().as('a').out().as('b').out().as('c').select('a','b','c')
+g.V().as('a').out().as('b').out().as('c').
+  select('a','b','c')
 ----
 
 In the above example, we tell Gremlin to iterate through all vertices and traverse _out_ twice from each. Gremlin
@@ -415,7 +432,7 @@ g.V().group().by(label)
 
 The use of `by()` here provides the mechanism by which to do the grouping. In this case, we've asked Gremlin to
 use the `label` (which, again, is an automatic static import from `T` in the console). We can't really tell much
-about our distribution though because we just have vertex unique identifiers as output. To make that nicer we
+about our distribution though because we just have unique identifiers of vertices as output. To make that nicer we
 could ask Gremlin to get us the value of the "name" property from those vertices, by supplying another `by()`
 modulator to `group()` to transform the values.
 
@@ -580,7 +597,7 @@ As mentioned earlier, Gremlin Server can also be configured with a WebSocket end
 embedded link:http://tinkerpop.apache.org/docs/x.y.z/reference/#_developing_a_driver[subprotocol] that allow a
 compliant driver to communicate with it.  TinkerPop supplies a
 link:http://tinkerpop.apache.org/docs/x.y.z/reference/#_connecting_via_java[reference driver] written in Java, but
-there are drivers developed by third-parties for other link:http://tinkerpop.apache.org/#graph-libraries[languages]
+there are drivers developed by both TinkerPop and third-parties for other link:http://tinkerpop.apache.org/#graph-libraries[languages]
 such as Python, Javascript, etc. Gremlin Server therefore represents the method by which non-JVM languages can
 interact with TinkerPop.