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 > > >
