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 >
