[DISCUSS] Getting "Practical Gremlin" more visibilty

[Stephen Mallette <sp...@gmail.com>]

I'm not sure what we should do about this, but Kelvin's book, Practical
Gremlin, is really the best thing out there for learning Gremlin. I mean,
we have lots of good documentation in TinkerPop for sure, but it is written
as more of a reference than a cohesive resource that you can go to for your
paced learning. So while we have more than enough documentation for users
to be able to figure out how to use our stuff, it's not quite the same
learning experience that Practical Gremlin is.

There's lots of good reason that it is the way it is. I think it's hard to
keep a cohesive style when lots of different authors contribute to the same
set of documents. We have also built our documentation in a very piecemeal
style as the software has evolved and it sorta reads that way. We did do
some smart things with "tutorials", but we don't have enough of them tying
together disparate parts of the documentation.Anyway....lucky for us,
Practical Gremlin is doing a great job of filling this gap.

What bothers me however, is that there are still developers who haven't
heard of the book! The message still isn't getting out there. The obvious
suggestion, which may have been made before, is that we place a link to the
book right on the TinkerPop home page. I think that would be a start, but I
think that perhaps even more visibility might be necessary. Maybe Practical
Gremlin needs a good logo? Thoughts on what a logo should look like? Maybe
we put the logo up there on the home page in place of where the "getting
started" tutorial is? Other ideas?

So the answer to all that might be "yes", "yes" and more "yes", but it is
important that we also consider that Practical Gremlin is a third-party
resource and that we would be linking away from the project documentation
in a reasonably public way. As an Apache project, it is my understanding
that our site should be the primary source for users to get their
information on how to use the software. I mostly just want to acknowledge
that point because as I mentioned earlier, I think TinkerPop has more than
sufficient reference documentation. It's not as though we link our
documentation to Practical Gremlin to give readers the source of
information. It in fact works the other way around - Practical Gremlin
treats our documentation as the reference (perhaps we could get a few more
links back to us in there too - hehe). I think that as long as that is
true, we satisfy our community requirements on documentation. Not sure if
anyone would argue against that....

So, with all that said, any thoughts on what I propose above?

Re: [DISCUSS] Getting "Practical Gremlin" more visibilty

[Stephen Mallette <sp...@gmail.com>]

The TinkerPop site is updated with the new logo/link.

On Fri, Jun 22, 2018 at 10:55 AM Stephen Mallette <sp...@gmail.com>
wrote:

> Here's the logo for Practical Gremlin:
>
>
> https://github.com/apache/tinkerpop/blob/master/docs/static/images/practical-gremlin.png
>
> Kelvin is going to work it into his site/git. I've already worked it into
> our documents/site. Once he's done, I'll publish everything on our end and
> we can promote the new logo together.
>
>
>
> On Mon, Jun 11, 2018 at 3:41 PM Ted Wilmes <tw...@gmail.com> wrote:
>
>> I'll register an official yes, yes, and yes. The docs will continue to
>> serve as the source of truth and de facto TinkerPop reference. Practical
>> Gremlin is a particularly good and comprehensive riff on that material
>> that
>> I think will resonate with many more folks if it is more easily found.
>> Perhaps when we come up with a logo or placement of that link, we can
>> notate it in such a manner that it is obviously a third party link.
>>
>> --Ted
>>
>> On Fri, Jun 8, 2018 at 2:50 PM, Stephen Mallette <sp...@gmail.com>
>> wrote:
>>
>> > I'm not sure what we should do about this, but Kelvin's book, Practical
>> > Gremlin, is really the best thing out there for learning Gremlin. I
>> mean,
>> > we have lots of good documentation in TinkerPop for sure, but it is
>> written
>> > as more of a reference than a cohesive resource that you can go to for
>> your
>> > paced learning. So while we have more than enough documentation for
>> users
>> > to be able to figure out how to use our stuff, it's not quite the same
>> > learning experience that Practical Gremlin is.
>> >
>> > There's lots of good reason that it is the way it is. I think it's hard
>> to
>> > keep a cohesive style when lots of different authors contribute to the
>> same
>> > set of documents. We have also built our documentation in a very
>> piecemeal
>> > style as the software has evolved and it sorta reads that way. We did do
>> > some smart things with "tutorials", but we don't have enough of them
>> tying
>> > together disparate parts of the documentation.Anyway....lucky for us,
>> > Practical Gremlin is doing a great job of filling this gap.
>> >
>> > What bothers me however, is that there are still developers who haven't
>> > heard of the book! The message still isn't getting out there. The
>> obvious
>> > suggestion, which may have been made before, is that we place a link to
>> the
>> > book right on the TinkerPop home page. I think that would be a start,
>> but I
>> > think that perhaps even more visibility might be necessary. Maybe
>> Practical
>> > Gremlin needs a good logo? Thoughts on what a logo should look like?
>> Maybe
>> > we put the logo up there on the home page in place of where the "getting
>> > started" tutorial is? Other ideas?
>> >
>> > So the answer to all that might be "yes", "yes" and more "yes", but it
>> is
>> > important that we also consider that Practical Gremlin is a third-party
>> > resource and that we would be linking away from the project
>> documentation
>> > in a reasonably public way. As an Apache project, it is my understanding
>> > that our site should be the primary source for users to get their
>> > information on how to use the software. I mostly just want to
>> acknowledge
>> > that point because as I mentioned earlier, I think TinkerPop has more
>> than
>> > sufficient reference documentation. It's not as though we link our
>> > documentation to Practical Gremlin to give readers the source of
>> > information. It in fact works the other way around - Practical Gremlin
>> > treats our documentation as the reference (perhaps we could get a few
>> more
>> > links back to us in there too - hehe). I think that as long as that is
>> > true, we satisfy our community requirements on documentation. Not sure
>> if
>> > anyone would argue against that....
>> >
>> > So, with all that said, any thoughts on what I propose above?
>> >
>>
>

Re: [DISCUSS] Getting "Practical Gremlin" more visibilty

[Stephen Mallette <sp...@gmail.com>]

Here's the logo for Practical Gremlin:

https://github.com/apache/tinkerpop/blob/master/docs/static/images/practical-gremlin.png

Kelvin is going to work it into his site/git. I've already worked it into
our documents/site. Once he's done, I'll publish everything on our end and
we can promote the new logo together.



On Mon, Jun 11, 2018 at 3:41 PM Ted Wilmes <tw...@gmail.com> wrote:

> I'll register an official yes, yes, and yes. The docs will continue to
> serve as the source of truth and de facto TinkerPop reference. Practical
> Gremlin is a particularly good and comprehensive riff on that material that
> I think will resonate with many more folks if it is more easily found.
> Perhaps when we come up with a logo or placement of that link, we can
> notate it in such a manner that it is obviously a third party link.
>
> --Ted
>
> On Fri, Jun 8, 2018 at 2:50 PM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > I'm not sure what we should do about this, but Kelvin's book, Practical
> > Gremlin, is really the best thing out there for learning Gremlin. I mean,
> > we have lots of good documentation in TinkerPop for sure, but it is
> written
> > as more of a reference than a cohesive resource that you can go to for
> your
> > paced learning. So while we have more than enough documentation for users
> > to be able to figure out how to use our stuff, it's not quite the same
> > learning experience that Practical Gremlin is.
> >
> > There's lots of good reason that it is the way it is. I think it's hard
> to
> > keep a cohesive style when lots of different authors contribute to the
> same
> > set of documents. We have also built our documentation in a very
> piecemeal
> > style as the software has evolved and it sorta reads that way. We did do
> > some smart things with "tutorials", but we don't have enough of them
> tying
> > together disparate parts of the documentation.Anyway....lucky for us,
> > Practical Gremlin is doing a great job of filling this gap.
> >
> > What bothers me however, is that there are still developers who haven't
> > heard of the book! The message still isn't getting out there. The obvious
> > suggestion, which may have been made before, is that we place a link to
> the
> > book right on the TinkerPop home page. I think that would be a start,
> but I
> > think that perhaps even more visibility might be necessary. Maybe
> Practical
> > Gremlin needs a good logo? Thoughts on what a logo should look like?
> Maybe
> > we put the logo up there on the home page in place of where the "getting
> > started" tutorial is? Other ideas?
> >
> > So the answer to all that might be "yes", "yes" and more "yes", but it is
> > important that we also consider that Practical Gremlin is a third-party
> > resource and that we would be linking away from the project documentation
> > in a reasonably public way. As an Apache project, it is my understanding
> > that our site should be the primary source for users to get their
> > information on how to use the software. I mostly just want to acknowledge
> > that point because as I mentioned earlier, I think TinkerPop has more
> than
> > sufficient reference documentation. It's not as though we link our
> > documentation to Practical Gremlin to give readers the source of
> > information. It in fact works the other way around - Practical Gremlin
> > treats our documentation as the reference (perhaps we could get a few
> more
> > links back to us in there too - hehe). I think that as long as that is
> > true, we satisfy our community requirements on documentation. Not sure if
> > anyone would argue against that....
> >
> > So, with all that said, any thoughts on what I propose above?
> >
>

Re: [DISCUSS] Getting "Practical Gremlin" more visibilty

[Ted Wilmes <tw...@gmail.com>]

I'll register an official yes, yes, and yes. The docs will continue to
serve as the source of truth and de facto TinkerPop reference. Practical
Gremlin is a particularly good and comprehensive riff on that material that
I think will resonate with many more folks if it is more easily found.
Perhaps when we come up with a logo or placement of that link, we can
notate it in such a manner that it is obviously a third party link.

--Ted

On Fri, Jun 8, 2018 at 2:50 PM, Stephen Mallette <sp...@gmail.com>
wrote:

> I'm not sure what we should do about this, but Kelvin's book, Practical
> Gremlin, is really the best thing out there for learning Gremlin. I mean,
> we have lots of good documentation in TinkerPop for sure, but it is written
> as more of a reference than a cohesive resource that you can go to for your
> paced learning. So while we have more than enough documentation for users
> to be able to figure out how to use our stuff, it's not quite the same
> learning experience that Practical Gremlin is.
>
> There's lots of good reason that it is the way it is. I think it's hard to
> keep a cohesive style when lots of different authors contribute to the same
> set of documents. We have also built our documentation in a very piecemeal
> style as the software has evolved and it sorta reads that way. We did do
> some smart things with "tutorials", but we don't have enough of them tying
> together disparate parts of the documentation.Anyway....lucky for us,
> Practical Gremlin is doing a great job of filling this gap.
>
> What bothers me however, is that there are still developers who haven't
> heard of the book! The message still isn't getting out there. The obvious
> suggestion, which may have been made before, is that we place a link to the
> book right on the TinkerPop home page. I think that would be a start, but I
> think that perhaps even more visibility might be necessary. Maybe Practical
> Gremlin needs a good logo? Thoughts on what a logo should look like? Maybe
> we put the logo up there on the home page in place of where the "getting
> started" tutorial is? Other ideas?
>
> So the answer to all that might be "yes", "yes" and more "yes", but it is
> important that we also consider that Practical Gremlin is a third-party
> resource and that we would be linking away from the project documentation
> in a reasonably public way. As an Apache project, it is my understanding
> that our site should be the primary source for users to get their
> information on how to use the software. I mostly just want to acknowledge
> that point because as I mentioned earlier, I think TinkerPop has more than
> sufficient reference documentation. It's not as though we link our
> documentation to Practical Gremlin to give readers the source of
> information. It in fact works the other way around - Practical Gremlin
> treats our documentation as the reference (perhaps we could get a few more
> links back to us in there too - hehe). I think that as long as that is
> true, we satisfy our community requirements on documentation. Not sure if
> anyone would argue against that....
>
> So, with all that said, any thoughts on what I propose above?
>