You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tinkerpop.apache.org by Bryn Cooke <br...@gmail.com> on 2015/09/28 20:50:12 UTC
Documentation g vs ts
Hi Tinkerpop,
I have fielded a couple of questions from some new Tinkerpop 3 users
recently and wonder if a slight tweak to the docs could make things
easier for those coming from TP2.
g = graph.traversal(standard())
For TP2 users this line is easy to miss, many people will just skim the
docs rather than read them from start to finish.
This is compounded by the fact that g was used as the 'graph' variable
in TP2 docs. The solution:
ts = graph.traversal(standard())
The object is a traversal source anyway, so calling it 'g' makes no
sense even for new TP users.
Cheers,
Bryn
Re: Documentation g vs ts
Posted by pieter <pi...@gmail.com>.
In my application code I have been calling it 'gt'.
Cheers
Pieter
On 28/09/2015 22:20, Matt Frantz wrote:
> Speaking as an application developer that experienced the introduction of
> the TraversalSource API, I can appreciate Bryn's perspective. However, I
> felt that "g" was more effective as a drop-in replacement for almost every
> piece of code where a TraversalSource was required (where previously a
> Graph had been). I made the change to use "graph" as the name of my Graph
> object. I also mentally redirected "g" to be an abbreviation for "Gremlin"
> ;)
>
> On Mon, Sep 28, 2015 at 11:50 AM, Bryn Cooke <br...@gmail.com> wrote:
>
>> Hi Tinkerpop,
>>
>> I have fielded a couple of questions from some new Tinkerpop 3 users
>> recently and wonder if a slight tweak to the docs could make things easier
>> for those coming from TP2.
>>
>> g = graph.traversal(standard())
>>
>> For TP2 users this line is easy to miss, many people will just skim the
>> docs rather than read them from start to finish.
>> This is compounded by the fact that g was used as the 'graph' variable in
>> TP2 docs. The solution:
>>
>> ts = graph.traversal(standard())
>>
>> The object is a traversal source anyway, so calling it 'g' makes no sense
>> even for new TP users.
>>
>> Cheers,
>> Bryn
>>
>>
Re: Documentation g vs ts
Posted by Matt Frantz <ma...@gmail.com>.
Speaking as an application developer that experienced the introduction of
the TraversalSource API, I can appreciate Bryn's perspective. However, I
felt that "g" was more effective as a drop-in replacement for almost every
piece of code where a TraversalSource was required (where previously a
Graph had been). I made the change to use "graph" as the name of my Graph
object. I also mentally redirected "g" to be an abbreviation for "Gremlin"
;)
On Mon, Sep 28, 2015 at 11:50 AM, Bryn Cooke <br...@gmail.com> wrote:
> Hi Tinkerpop,
>
> I have fielded a couple of questions from some new Tinkerpop 3 users
> recently and wonder if a slight tweak to the docs could make things easier
> for those coming from TP2.
>
> g = graph.traversal(standard())
>
> For TP2 users this line is easy to miss, many people will just skim the
> docs rather than read them from start to finish.
> This is compounded by the fact that g was used as the 'graph' variable in
> TP2 docs. The solution:
>
> ts = graph.traversal(standard())
>
> The object is a traversal source anyway, so calling it 'g' makes no sense
> even for new TP users.
>
> Cheers,
> Bryn
>
>
Re: Documentation g vs ts
Posted by Stephen Mallette <sp...@gmail.com>.
Nice idea - consolidating all those random blocks into one place should
make it easier for those in transition.
On Tue, Sep 29, 2015 at 10:01 AM, Marko Rodriguez <ok...@gmail.com>
wrote:
> Hi,
>
> Bryn, if you do a "Migrating from TinkerPop2" section, can you please go
> through and grab all the NOTE:, IMPORTANT:, CAUTION: pull out block quotes
> throughout that are of that vein (i.e. those that are like "In TinkerPop2,
> blah blah blah…"). There are also some non-blockquotes and images here and
> there that can be pulled into your section (in particular a part about
> Traversers).
>
> Thanks,
> Marko.
>
> http://markorodriguez.com
>
> On Sep 29, 2015, at 7:04 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > I think folks would find a "Migrating from TP2" section helpful. Sounds
> > good to me...thanks.
> >
> > On Tue, Sep 29, 2015 at 7:47 AM, Bryn Cooke <br...@gmail.com> wrote:
> >
> >> OK, I'll provide a pull request for the docs, perhaps in the form of a
> >> short section with a heading 'Migrating from TP2'
> >>
> >> Cheers,
> >> Bryn
> >>
> >> On 28/09/15 20:18, Stephen Mallette wrote:
> >>
> >>> My answer wasn't great - let me add a little more. I don't think we
> >>> should
> >>> generally go to naming TraversalSource as "ts" because the name you
> give
> >>> to
> >>> this variable should generally be representative of the context of the
> >>> TraversalSource itself. This ultimately ties all the way up to Gremlin
> >>> Server in how you reference the TraversalSource you want to refer to
> and
> >>> there are multiple TraversalSource objects at play. We need to
> continue
> >>> to
> >>> convey to folks that they should think of "g" as a default name when
> you
> >>> have a single source configured. I know that might not eliminate the
> >>> initial confusion for folks, but I think we've discussed the naming of
> "g"
> >>> before and that any initial confusion should probably be short-lived.
> >>>
> >>> +1 for a CAUTION: as suggested by Marko.
> >>>
> >>> On Mon, Sep 28, 2015 at 3:00 PM, Marko Rodriguez <okrammarko@gmail.com
> >
> >>> wrote:
> >>>
> >>> Hi,
> >>>>
> >>>> Bryn: you could provide a pull request for some sort of blockquote
> that
> >>>> explains the distinction so it makes it easier for the community (as a
> >>>> permeating entity across all space and time) to know whats going on.
> >>>>
> >>>> E.g.
> >>>>
> >>>> CAUTION: In TinkerPop3, `g`….in TinkerPop3…
> >>>>
> >>>> Marko.
> >>>>
> >>>> http://markorodriguez.com
> >>>>
> >>>> On Sep 28, 2015, at 12:56 PM, Stephen Mallette <sp...@gmail.com>
> >>>> wrote:
> >>>>
> >>>> I dunno, Bryn. I kinda get your point, but:
> >>>>>
> >>>>> ts.V()
> >>>>>
> >>>>> looks so wrong - however:
> >>>>>
> >>>>> g.V()
> >>>>>
> >>>>> ahhh - all is right with the universe. :D
> >>>>>
> >>>>>
> >>>>>
> >>>>> On Mon, Sep 28, 2015 at 2:50 PM, Bryn Cooke <br...@gmail.com>
> >>>>> wrote:
> >>>>>
> >>>>> Hi Tinkerpop,
> >>>>>>
> >>>>>> I have fielded a couple of questions from some new Tinkerpop 3 users
> >>>>>> recently and wonder if a slight tweak to the docs could make things
> >>>>>>
> >>>>> easier
> >>>>
> >>>>> for those coming from TP2.
> >>>>>>
> >>>>>> g = graph.traversal(standard())
> >>>>>>
> >>>>>> For TP2 users this line is easy to miss, many people will just skim
> the
> >>>>>> docs rather than read them from start to finish.
> >>>>>> This is compounded by the fact that g was used as the 'graph'
> variable
> >>>>>>
> >>>>> in
> >>>>
> >>>>> TP2 docs. The solution:
> >>>>>>
> >>>>>> ts = graph.traversal(standard())
> >>>>>>
> >>>>>> The object is a traversal source anyway, so calling it 'g' makes no
> >>>>>>
> >>>>> sense
> >>>>
> >>>>> even for new TP users.
> >>>>>>
> >>>>>> Cheers,
> >>>>>> Bryn
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>
> >>
>
>
Re: Documentation g vs ts
Posted by Marko Rodriguez <ok...@gmail.com>.
Hi,
Bryn, if you do a "Migrating from TinkerPop2" section, can you please go through and grab all the NOTE:, IMPORTANT:, CAUTION: pull out block quotes throughout that are of that vein (i.e. those that are like "In TinkerPop2, blah blah blah…"). There are also some non-blockquotes and images here and there that can be pulled into your section (in particular a part about Traversers).
Thanks,
Marko.
http://markorodriguez.com
On Sep 29, 2015, at 7:04 AM, Stephen Mallette <sp...@gmail.com> wrote:
> I think folks would find a "Migrating from TP2" section helpful. Sounds
> good to me...thanks.
>
> On Tue, Sep 29, 2015 at 7:47 AM, Bryn Cooke <br...@gmail.com> wrote:
>
>> OK, I'll provide a pull request for the docs, perhaps in the form of a
>> short section with a heading 'Migrating from TP2'
>>
>> Cheers,
>> Bryn
>>
>> On 28/09/15 20:18, Stephen Mallette wrote:
>>
>>> My answer wasn't great - let me add a little more. I don't think we
>>> should
>>> generally go to naming TraversalSource as "ts" because the name you give
>>> to
>>> this variable should generally be representative of the context of the
>>> TraversalSource itself. This ultimately ties all the way up to Gremlin
>>> Server in how you reference the TraversalSource you want to refer to and
>>> there are multiple TraversalSource objects at play. We need to continue
>>> to
>>> convey to folks that they should think of "g" as a default name when you
>>> have a single source configured. I know that might not eliminate the
>>> initial confusion for folks, but I think we've discussed the naming of "g"
>>> before and that any initial confusion should probably be short-lived.
>>>
>>> +1 for a CAUTION: as suggested by Marko.
>>>
>>> On Mon, Sep 28, 2015 at 3:00 PM, Marko Rodriguez <ok...@gmail.com>
>>> wrote:
>>>
>>> Hi,
>>>>
>>>> Bryn: you could provide a pull request for some sort of blockquote that
>>>> explains the distinction so it makes it easier for the community (as a
>>>> permeating entity across all space and time) to know whats going on.
>>>>
>>>> E.g.
>>>>
>>>> CAUTION: In TinkerPop3, `g`….in TinkerPop3…
>>>>
>>>> Marko.
>>>>
>>>> http://markorodriguez.com
>>>>
>>>> On Sep 28, 2015, at 12:56 PM, Stephen Mallette <sp...@gmail.com>
>>>> wrote:
>>>>
>>>> I dunno, Bryn. I kinda get your point, but:
>>>>>
>>>>> ts.V()
>>>>>
>>>>> looks so wrong - however:
>>>>>
>>>>> g.V()
>>>>>
>>>>> ahhh - all is right with the universe. :D
>>>>>
>>>>>
>>>>>
>>>>> On Mon, Sep 28, 2015 at 2:50 PM, Bryn Cooke <br...@gmail.com>
>>>>> wrote:
>>>>>
>>>>> Hi Tinkerpop,
>>>>>>
>>>>>> I have fielded a couple of questions from some new Tinkerpop 3 users
>>>>>> recently and wonder if a slight tweak to the docs could make things
>>>>>>
>>>>> easier
>>>>
>>>>> for those coming from TP2.
>>>>>>
>>>>>> g = graph.traversal(standard())
>>>>>>
>>>>>> For TP2 users this line is easy to miss, many people will just skim the
>>>>>> docs rather than read them from start to finish.
>>>>>> This is compounded by the fact that g was used as the 'graph' variable
>>>>>>
>>>>> in
>>>>
>>>>> TP2 docs. The solution:
>>>>>>
>>>>>> ts = graph.traversal(standard())
>>>>>>
>>>>>> The object is a traversal source anyway, so calling it 'g' makes no
>>>>>>
>>>>> sense
>>>>
>>>>> even for new TP users.
>>>>>>
>>>>>> Cheers,
>>>>>> Bryn
>>>>>>
>>>>>>
>>>>>>
>>>>
>>
Re: Documentation g vs ts
Posted by Stephen Mallette <sp...@gmail.com>.
I think folks would find a "Migrating from TP2" section helpful. Sounds
good to me...thanks.
On Tue, Sep 29, 2015 at 7:47 AM, Bryn Cooke <br...@gmail.com> wrote:
> OK, I'll provide a pull request for the docs, perhaps in the form of a
> short section with a heading 'Migrating from TP2'
>
> Cheers,
> Bryn
>
> On 28/09/15 20:18, Stephen Mallette wrote:
>
>> My answer wasn't great - let me add a little more. I don't think we
>> should
>> generally go to naming TraversalSource as "ts" because the name you give
>> to
>> this variable should generally be representative of the context of the
>> TraversalSource itself. This ultimately ties all the way up to Gremlin
>> Server in how you reference the TraversalSource you want to refer to and
>> there are multiple TraversalSource objects at play. We need to continue
>> to
>> convey to folks that they should think of "g" as a default name when you
>> have a single source configured. I know that might not eliminate the
>> initial confusion for folks, but I think we've discussed the naming of "g"
>> before and that any initial confusion should probably be short-lived.
>>
>> +1 for a CAUTION: as suggested by Marko.
>>
>> On Mon, Sep 28, 2015 at 3:00 PM, Marko Rodriguez <ok...@gmail.com>
>> wrote:
>>
>> Hi,
>>>
>>> Bryn: you could provide a pull request for some sort of blockquote that
>>> explains the distinction so it makes it easier for the community (as a
>>> permeating entity across all space and time) to know whats going on.
>>>
>>> E.g.
>>>
>>> CAUTION: In TinkerPop3, `g`….in TinkerPop3…
>>>
>>> Marko.
>>>
>>> http://markorodriguez.com
>>>
>>> On Sep 28, 2015, at 12:56 PM, Stephen Mallette <sp...@gmail.com>
>>> wrote:
>>>
>>> I dunno, Bryn. I kinda get your point, but:
>>>>
>>>> ts.V()
>>>>
>>>> looks so wrong - however:
>>>>
>>>> g.V()
>>>>
>>>> ahhh - all is right with the universe. :D
>>>>
>>>>
>>>>
>>>> On Mon, Sep 28, 2015 at 2:50 PM, Bryn Cooke <br...@gmail.com>
>>>> wrote:
>>>>
>>>> Hi Tinkerpop,
>>>>>
>>>>> I have fielded a couple of questions from some new Tinkerpop 3 users
>>>>> recently and wonder if a slight tweak to the docs could make things
>>>>>
>>>> easier
>>>
>>>> for those coming from TP2.
>>>>>
>>>>> g = graph.traversal(standard())
>>>>>
>>>>> For TP2 users this line is easy to miss, many people will just skim the
>>>>> docs rather than read them from start to finish.
>>>>> This is compounded by the fact that g was used as the 'graph' variable
>>>>>
>>>> in
>>>
>>>> TP2 docs. The solution:
>>>>>
>>>>> ts = graph.traversal(standard())
>>>>>
>>>>> The object is a traversal source anyway, so calling it 'g' makes no
>>>>>
>>>> sense
>>>
>>>> even for new TP users.
>>>>>
>>>>> Cheers,
>>>>> Bryn
>>>>>
>>>>>
>>>>>
>>>
>
Re: Documentation g vs ts
Posted by Bryn Cooke <br...@gmail.com>.
OK, I'll provide a pull request for the docs, perhaps in the form of a
short section with a heading 'Migrating from TP2'
Cheers,
Bryn
On 28/09/15 20:18, Stephen Mallette wrote:
> My answer wasn't great - let me add a little more. I don't think we should
> generally go to naming TraversalSource as "ts" because the name you give to
> this variable should generally be representative of the context of the
> TraversalSource itself. This ultimately ties all the way up to Gremlin
> Server in how you reference the TraversalSource you want to refer to and
> there are multiple TraversalSource objects at play. We need to continue to
> convey to folks that they should think of "g" as a default name when you
> have a single source configured. I know that might not eliminate the
> initial confusion for folks, but I think we've discussed the naming of "g"
> before and that any initial confusion should probably be short-lived.
>
> +1 for a CAUTION: as suggested by Marko.
>
> On Mon, Sep 28, 2015 at 3:00 PM, Marko Rodriguez <ok...@gmail.com>
> wrote:
>
>> Hi,
>>
>> Bryn: you could provide a pull request for some sort of blockquote that
>> explains the distinction so it makes it easier for the community (as a
>> permeating entity across all space and time) to know whats going on.
>>
>> E.g.
>>
>> CAUTION: In TinkerPop3, `g`….in TinkerPop3…
>>
>> Marko.
>>
>> http://markorodriguez.com
>>
>> On Sep 28, 2015, at 12:56 PM, Stephen Mallette <sp...@gmail.com>
>> wrote:
>>
>>> I dunno, Bryn. I kinda get your point, but:
>>>
>>> ts.V()
>>>
>>> looks so wrong - however:
>>>
>>> g.V()
>>>
>>> ahhh - all is right with the universe. :D
>>>
>>>
>>>
>>> On Mon, Sep 28, 2015 at 2:50 PM, Bryn Cooke <br...@gmail.com> wrote:
>>>
>>>> Hi Tinkerpop,
>>>>
>>>> I have fielded a couple of questions from some new Tinkerpop 3 users
>>>> recently and wonder if a slight tweak to the docs could make things
>> easier
>>>> for those coming from TP2.
>>>>
>>>> g = graph.traversal(standard())
>>>>
>>>> For TP2 users this line is easy to miss, many people will just skim the
>>>> docs rather than read them from start to finish.
>>>> This is compounded by the fact that g was used as the 'graph' variable
>> in
>>>> TP2 docs. The solution:
>>>>
>>>> ts = graph.traversal(standard())
>>>>
>>>> The object is a traversal source anyway, so calling it 'g' makes no
>> sense
>>>> even for new TP users.
>>>>
>>>> Cheers,
>>>> Bryn
>>>>
>>>>
>>
Re: Documentation g vs ts
Posted by Stephen Mallette <sp...@gmail.com>.
My answer wasn't great - let me add a little more. I don't think we should
generally go to naming TraversalSource as "ts" because the name you give to
this variable should generally be representative of the context of the
TraversalSource itself. This ultimately ties all the way up to Gremlin
Server in how you reference the TraversalSource you want to refer to and
there are multiple TraversalSource objects at play. We need to continue to
convey to folks that they should think of "g" as a default name when you
have a single source configured. I know that might not eliminate the
initial confusion for folks, but I think we've discussed the naming of "g"
before and that any initial confusion should probably be short-lived.
+1 for a CAUTION: as suggested by Marko.
On Mon, Sep 28, 2015 at 3:00 PM, Marko Rodriguez <ok...@gmail.com>
wrote:
> Hi,
>
> Bryn: you could provide a pull request for some sort of blockquote that
> explains the distinction so it makes it easier for the community (as a
> permeating entity across all space and time) to know whats going on.
>
> E.g.
>
> CAUTION: In TinkerPop3, `g`….in TinkerPop3…
>
> Marko.
>
> http://markorodriguez.com
>
> On Sep 28, 2015, at 12:56 PM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > I dunno, Bryn. I kinda get your point, but:
> >
> > ts.V()
> >
> > looks so wrong - however:
> >
> > g.V()
> >
> > ahhh - all is right with the universe. :D
> >
> >
> >
> > On Mon, Sep 28, 2015 at 2:50 PM, Bryn Cooke <br...@gmail.com> wrote:
> >
> >> Hi Tinkerpop,
> >>
> >> I have fielded a couple of questions from some new Tinkerpop 3 users
> >> recently and wonder if a slight tweak to the docs could make things
> easier
> >> for those coming from TP2.
> >>
> >> g = graph.traversal(standard())
> >>
> >> For TP2 users this line is easy to miss, many people will just skim the
> >> docs rather than read them from start to finish.
> >> This is compounded by the fact that g was used as the 'graph' variable
> in
> >> TP2 docs. The solution:
> >>
> >> ts = graph.traversal(standard())
> >>
> >> The object is a traversal source anyway, so calling it 'g' makes no
> sense
> >> even for new TP users.
> >>
> >> Cheers,
> >> Bryn
> >>
> >>
>
>
Re: Documentation g vs ts
Posted by Marko Rodriguez <ok...@gmail.com>.
Hi,
Bryn: you could provide a pull request for some sort of blockquote that explains the distinction so it makes it easier for the community (as a permeating entity across all space and time) to know whats going on.
E.g.
CAUTION: In TinkerPop3, `g`….in TinkerPop3…
Marko.
http://markorodriguez.com
On Sep 28, 2015, at 12:56 PM, Stephen Mallette <sp...@gmail.com> wrote:
> I dunno, Bryn. I kinda get your point, but:
>
> ts.V()
>
> looks so wrong - however:
>
> g.V()
>
> ahhh - all is right with the universe. :D
>
>
>
> On Mon, Sep 28, 2015 at 2:50 PM, Bryn Cooke <br...@gmail.com> wrote:
>
>> Hi Tinkerpop,
>>
>> I have fielded a couple of questions from some new Tinkerpop 3 users
>> recently and wonder if a slight tweak to the docs could make things easier
>> for those coming from TP2.
>>
>> g = graph.traversal(standard())
>>
>> For TP2 users this line is easy to miss, many people will just skim the
>> docs rather than read them from start to finish.
>> This is compounded by the fact that g was used as the 'graph' variable in
>> TP2 docs. The solution:
>>
>> ts = graph.traversal(standard())
>>
>> The object is a traversal source anyway, so calling it 'g' makes no sense
>> even for new TP users.
>>
>> Cheers,
>> Bryn
>>
>>
Re: Documentation g vs ts
Posted by Stephen Mallette <sp...@gmail.com>.
I dunno, Bryn. I kinda get your point, but:
ts.V()
looks so wrong - however:
g.V()
ahhh - all is right with the universe. :D
On Mon, Sep 28, 2015 at 2:50 PM, Bryn Cooke <br...@gmail.com> wrote:
> Hi Tinkerpop,
>
> I have fielded a couple of questions from some new Tinkerpop 3 users
> recently and wonder if a slight tweak to the docs could make things easier
> for those coming from TP2.
>
> g = graph.traversal(standard())
>
> For TP2 users this line is easy to miss, many people will just skim the
> docs rather than read them from start to finish.
> This is compounded by the fact that g was used as the 'graph' variable in
> TP2 docs. The solution:
>
> ts = graph.traversal(standard())
>
> The object is a traversal source anyway, so calling it 'g' makes no sense
> even for new TP users.
>
> Cheers,
> Bryn
>
>