Basic usage instructions

[joostdevries]

Not sure where/how yet. But regarding what:

• twiddle.json - What to put there/how/what
• autorun/reload
• ...

[acorncom]

Is using Hopscotch too "tutorial-like"? It's one of the best tutorial systems I've seen out there. There is a package, but doesn't look like it's doing much more than adding in the necessary bower / JS files: https://www.npmjs.com/package/ember-hopscotch

If using something like this, we could add a "Take the Tour" menu item under Help and start the tour from there. That way we'd keep it out of the way for "pro" users, but it'd be fairly easy to find for newcomers ...

[Gaurav0]

@acorncom Nope. I like hopscotch. I think it would be cool. @joostdevries ?

[acorncom]

@joostdevries if you like the idea I can prototype something on this at some point so we can experiment with it ...

[joostdevries]

To be honest, I think that would be overkill for wat we need here. I think people just want a quick reference instead of a full blown walkthrough. Maybe just using the README.

[acorncom]

Sounds good. Probably is indeed overkill. Here's an entirely different thought. Any chance we could have the "default template" for the system be the read me? With basic comments, etc sprinkled in to the controller / template? It'd end up being super light weight (and only visible to folks making a new Twiddle), but might get new folks started while staying out of the way of people who know what to do ...

[joostdevries]

@acorncom really like the idea but a little worried about people landing on a shared Twiddle (which is a primary use-case)

[acorncom]

@joostdevries Good point. Hmm ...

You outlined two items above (the twiddle.json and the autorun/reload). Is there anything else that needs explanation? If not, would it be possible to embed basic "help" boilerplate in the twiddle.json file (which I'd assume would need to be stripped out before running :-/)? Seems like that's the part of the system currently that might need documenting ...

Live reload seems to make sense on its own ...

What I've found is that if there are helpful docs in a file, I'll leave them in even if I already know how to use the file, because it's a nice for quick reference in the future. So in a shared Twiddle case, it might be reasonable to assume that the help info would still be there ...

[Gaurav0]

Unfortunately, the official JSON format does not allow for comments.

[acorncom]

@Gaurav0 Yeah, I know :-/ Hence wondering if we could strip comments out prior to using the JSON file. That looks like it could be a pain though. Another option would be shifting to a twiddle.js file, which might make it easier to make future changes?

[Gaurav0]

@acorncom The last thing I want is to eval more javascript code. :)

[acorncom]

@Gaurav0 :-D

[acorncom]

Guys, can we go back to my earlier question? What needs to be explained?

If it's primarily the twiddle.json file, how about this for a different idea ...

If we're displaying the twiddle.json file, show a ? button somewhere near the file with context specific information about it. In the long-run, we could have quick pointers on various types of files if desired ...

Possible locations:

• near the file dropdown
• upper right corner of the file editor itself (location chosen so it doesn't conflict with text lines generally but is still clearly related to the specific file

Thoughts?

I should also clarify that I'm not just brainstorming about work for you guys to do, but would be happy to help once we've chosen a direction :-)

[Gaurav0]

@acorncom Right now, most people need help:

1. Figuring out how to add dependencies (via twiddle.json)
2. retrieving a twiddle (gist) they have saved
3. Figuring out how to add CSS
4. Figuring out how to do routing
5. Troubleshooting / debugging their twiddle
6. Navigating their twiddle
7. Figuring out what to name files so that they are found.

I personally think these are best fixed with PRs making these things easier. Some are just issues with learning Ember and Ember CLI. Usage instructions can't fix everything. We also need a way to keep any instructions up to date.

I have to defer to @joostdevries about how exactly to implement usage instructions, though, given that we disagree.