Sounds like a great way to start. We can develop our Gherkin idioms in the tutorial context, and those would serve us well to "back-fill" into the other areas.
On Mon, Jul 13, 2015 at 11:09 AM, Stephen Mallette <[email protected]> wrote: > We're a bit off of matthias' original topic of the "home page" but perhaps > we think of a tooling gremlindocs recipes up with cucumber as a model. > Then once the model is solid and proven we can consider where it fits into > existing docs. Since gremlindocs is a blank slate, it shouldn't be too > hard to get something in place. Good starting point? > > On Mon, Jul 13, 2015 at 1:53 PM, Matt Frantz <[email protected]> > wrote: > > > It looks like there is tooling for integrating Gherkin feature files into > > asciidoc. > > > > https://github.com/domgold/asciidoctor-gherkin-extension > > > > I would only propose using Cucumber if it replaces a large part of our > docs > > and testing. It's not worthwhile to create a redundant set of > docs/tests. > > To me, what is in scope to replace with Cucumber includes the following: > > > > - gremlindocs.com (which could host a set of feature files, one per > > "recipe") > > - the-traversal.asciidoc (which could be repurposed as an index for > > step-specific feature files) > > - gremlin-test (especially the step tests) > > > > > > On Mon, Jul 13, 2015 at 4:01 AM, Stephen Mallette <[email protected]> > > wrote: > > > > > Matthias, I've had similar feedback on the home page from folks. It's > a > > > good collection of links for TinkerPop informational purposes but > doesn't > > > really convey much information about TinkerPop itself. I don't think > you > > > can get access to modify the home page directly as you need apache svn > > > access to do that (maybe you can checkout as read-only). If you were > to > > > make changes, I guess you could modify it and then screenshot/pdf it > for > > > review - before marko or i commit the changes?? not sure sure if there > > is a > > > better flow than that. > > > > > > As we talk about user documentation, a separate issue is what should > > happen > > > with gremlindocs.com. I think the new tp3 documentation covers most > of > > > what gremlindocs.com tried to do in that it provided docs on all the > > > available steps with examples. I sort of had it in mind that > gremlindocs > > > would become a place for recipes (e.g. shortest path), but I'm not sure > > > that's all it should be. If anyone has any thoughts on the matter > please > > > let me know. > > > > > > Matt - how would you envision feature files getting rolled into > asciidoc > > > generation? or is what you're suggesting separate and an additional > > > resource to users? > > > > > > > > > > > > On Sat, Jul 11, 2015 at 6:52 PM, Matt Frantz < > [email protected] > > > > > > wrote: > > > > > > > I've been drawn to BDD and Cucumber recently, and feel that having > the > > > > behavioral description of TP3 written largely in Gherkin could serve > > > > multiple purposes admirably. > > > > > > > > Firstly, in Gherkin, one could write "lessons" or "tutorials" on > > specific > > > > features. For example, individual steps could have a feature, but > also > > > > more complex use cases involving multiple steps. Each feature file > > could > > > > be a coherent lesson, and a sequence of feature files could be > designed > > > to > > > > provide newcomers with guided trails through the documentation. In > > some > > > > lessons, one could explore multiple solutions to the same problem, > > > pointing > > > > out advantages of each. > > > > > > > > Secondly, since Cucumber provides the ability to automate and enforce > > the > > > > behavioral descriptions, I feel that the investment would pay > dividends > > > > when used in place of the existing JUnit test suites. Many of the > > > existing > > > > JUnit tests lack context. While they are intended to enforce vendor > > > > conformance, we have lost the "why" of each test. > > > > > > > > This migration would not happen overnight, but I think that with the > > > > deficit of Javadoc within the code, and the deficiencies that > Matthias > > > > points out in the home page, we should consider carefully how to > bridge > > > the > > > > gap. > > > > > > > > On Sat, Jul 11, 2015 at 12:25 PM, Matthias Broecheler < > > [email protected]> > > > > wrote: > > > > > > > > > Hi guys, > > > > > > > > > > over the last couple of weeks (in particular after presenting on > TP3 > > in > > > > > Seattle at the end of June) I have gotten some feedback from a > number > > > of > > > > > folks who wanted to try out TP3 but didn't know where to start or > > what > > > to > > > > > do. > > > > > A lot of that comes back to the current homepage: > > > > > http://tinkerpop.incubator.apache.org/ > > > > > > > > > > While this page contains all the information experienced TP users > > would > > > > > want to find, newbies seem to get lost: > > > > > - It doesn't really explain what TinkerPop is or does beyond the > > > generic > > > > > statement "provides graph computing capabilities". Why should > > somebody > > > > care > > > > > about TP3? What does it do specifically? What does it look like in > > > > > practice? > > > > > - There is no "Getting Started". While the documentation is a > > > beautifully > > > > > written and comprehensive document, for a total newcomer it is very > > > > > overwhelming. > > > > > > > > > > Not saying that the website is bad, but that it doesn't serve > > newcomers > > > > and > > > > > interested developers very well. > > > > > I would suggest that we delegate some information (e.g. 3rd party > > > > > libraries, how to contribute) to subpages and use the homepage to > > help > > > > > newcomers figure out what this is. > > > > > I think Apache Spark does a reasonable job at this: > > > > > https://spark.apache.org/ > > > > > > > > > > Would you guys mind if I took a crack at this with Daniel's help on > > > > getting > > > > > started and some examples? If so, how can I get access to the page > to > > > > make > > > > > some suggested changes? > > > > > > > > > > Thanks, > > > > > Matthias > > > > > > > > > > > > > > >
