Quickstart doesn't help you to start

[still-dreaming-1]

The supposed "quickstart" is one of the worst quickstart tutorials I have ever seen. It is extremely irritating and demotivating. As far as I can tell it does not contain any information about how to actually get started. It just explains concepts and lets you type in code and run stuff from inside the quickstart itself. This is the worst context to actually get started because there is no context for how this fits into actually getting started with your own thing and you are not getting started with your own thing you are just playing around with an already provided thing.

[DeGuitard]

While it is said quite harshly, I concur. I can't find a "recommended" way to actually create an eve program.

In my humble opinion, the quickstart tutorial should provide the following informations:

• How to initialize a new project ;
• How to write a "Hello world" code ;
• Understand why we wrote "Hello world" this way (i.e. the underlying concepts) ;
• How to test your code ;
• How to build and deliver it somewhere (out of the IDE).

Currently, based on the quickstart tutorial I only know the main concepts of Eve - which is good, as these concepts are quite unusual.

[vickychijwani]

This is simply because the things you mentioned are just not supported at the moment - you currently cannot run Eve programs outside its IDE, deploy them, or integrate with an existing codebase in another language. If that makes it sound like Eve oversold itself, consider how different it is from everything else out there, and that this is a v0.2 release.

From what I gathered by reading several blog posts, the Eve team wanted to get the language / programming model out there for feedback, without letting the immaturity of the tooling hold it back (can't remember where I read that, will try to find the post).

[still-dreaming-1]

In my opinion the best way for them to get feedback would be to have something usable, even if it is not good or production ready yet. That means the code should at least be runnable outside the IDE or at least have a way to fake this where you see the code running without also seeing the code. A quickstart should start with creating a new thing. If that is not what they want to do they should at least have the quickstart have you setup your own new example as the first thing you do even if it has to run in the IDE.

[piersmana]

@still-dreaming-1 The Lean Startup discusses the importance of MVPs to get feedback as early as possible. First sentence of the README:

Eve is a set of tools to help us think. Currently, these tools include: a temporal query language, a compiler, and a database.

And to your comments:

Please let us know what kind of documents would be the most helpful as you begin your journey with Eve. We want our documentation to be a highlight of the Eve experience, so any suggestions are greatly appreciated.

[ibdknox]

There will always be bugs and aspects of Eve people won't like and constructive feedback is always welcome. The aggressive tone of the original post on this issue however, is not befitting of the inclusive community we want to build around Eve. Please be respectful and considerate of others when providing feedback.

Setting the tone aside, I think the feedback here is spot on. Originally the quick start was meant to help you get accustomed to the language, but you are entirely correct that it leaves you with nowhere to go from there. There are also definitely parts of it where the phrasing is confusing and overly verbose. I think we can shave it down some and clear it up a lot. @cmontella owns that side of the story, but is off to a wedding until next week. As soon as he's back, we'll clean this up and post on this issue to get feedback on the changes.

[still-dreaming-1]

I'm not normally that aggressive with my tone, so that in itself is a form of feedback. Trying to go through the tutorial put me in an extremely aggravated mood.

[still-dreaming-1]

I do apologize for my tone, I don't know what got into me that I was so condescending and not wanting to apologize sooner...

I will try to give a more specific recommendation. If making a new page is not supported yet, maybe the next step should be to rename the tutorial from "Quick Start" to "First Concepts" or something like that.

[Rhynri]

I had a similar feeling about the "Quick Start". I'd suggest ordering it as follows -

1. A brief but concise breakdown on what Eve is, and what it isn't. BEFORE first code block. I know a lot of quick starts do it differently, but Eve is different. Start with that difference. Then surprise people with the fact they are reading executable code. This is your cannonball, make a splash!
2. "(If you wish to follow along on your own machine, instructions on how to do so are here[link].)" This allows people to walk through the quick-start on their own machine, or perhaps even do their own program alongside it. I frequently do the latter. It's not at all obvious currently where these instructions are if you aren't a GitHub user. As a link it doesn't distract from the quick start with a bunch of text.
3. Hello world block. How everything is a record. What binding to @browser means.
4. Second code block.
5. An explanation of what our @browser looks like behind the scenes (simplistically) at this point in a graphic representation for people who learn that way. Also helps drive home the point that Eve is non-linear.
6. Commit code block.
7. This explanation is quite convoluted. Use of white-space could also improve the ability to tell which block of text relates to which code-block.
8. #div block and explanation
9. #student block and explanation
10. celia = [name: "Celia"] block. The explanation for this was clear as mud to me the first time I read it. Explaining what is happening to the record might help with clarity.
11. commit #student block. A tree diagram or something of that sort might help explain how #student isn't a single record, and why Jermaine doesn't match, although if you understand 9, 10 comes easier.
12. [more blocks]
13. (name equivalency blocks) Took me two full read-thrus for this to register. The solution isn't very obvious either: Why does schools.name work, and where does students.name come from? Then it says "creates an implicit join", which alone is going to lose a few people. A lot of clarity to be desired here.

These are all merely suggestions, thoughts, whatever you wish to call them. Take them with a grain of salt as such. Some are things that confused me, many are things I could see confusing me if I wasn't a programmer.

[cmontella]

I'm going to give it another go today, I'll post here when I've committed a revision and we can tweak it from there.