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 <[email protected]> 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? >
