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.

[gdufford]

Hey guys,

I'm really wanting to use Twiddle since being pointed at it by Frank at Ember Igniter. However, I'm an Ember noob and it's baffling to me. It seem "like" cli, but not exactly. I've spent the last few hours trying to build out a simple twiddle with fixture data and nothing works.

This last post by @Gaurav0 sounds like the problem with learning to use Twiddle are known, has anything been done and I've missed it?

Thanks!

[sheriffderek]

@acorncom An outline of how things work would be helpful to me, being a person who is CLI all the way. I was tempted to build a starting point for a series of example, and I used the CLI folder structure I'm used to / but that doesn't work. Is it POD structure? Is there a simplified structure that keeps twiddle rad? If so, what is it?

I'd also be interested to know what twiddle doesn't have yet. For example, can I add an Adapter? Can I use a serializer? Can I pull in data from an external API? What are the limitations? I'll love it either way, but I wont love wondering what I can and can't expect.

Saved twiddles are easy to retrieve now as far as I can see, but the list @Gaurav0 was starting was good.

I'd order it based on complexity. Folder structure and Routing and general limitations seem like things I would teach someone very early. Then probably adding other dependencies. Then styles.

[sheriffderek]

I find myself coming to ask some questions - and make some suggestions / but I see I'm just a broken record, and I've already had this thought above.

How can I help?

[Gaurav0]

Write a PR. Almost anything is better than what we have now. :)

[acorncom]

@sheriffderek if you have the time to think about this, I think it'd be worth revisiting this. We could put a "Using Twiddle" link under the Help menu and then start adding instructions in there ...

[Gaurav0]

Hi all, we don't have to start by using Hopscotch or anything complicated. I can propose as a start we can create a markdown file in the github repo and then add a link to it from the app?

@MelSumner maybe you can consider finding someone to help write it? I'll be happy to work with them.

[acorncom]

@Gaurav0 is the below twiddle.json a good example of the various options that twiddle supports? What else is missing?

{
  "version": "0.13.1",
  "ENV": {
    "ember-cli-mirage": {
      "enabled": true
    }
  },
  "EmberENV": {
    "FEATURES": {}
  },
  "options": {
    "use_pods": false,
    "enable-testing": false
  },
  "dependencies": {
    "jquery": "https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.js",
    "ember": "2.16.2",
    "ember-template-compiler": "2.16.2",
    "ember-testing": "2.16.2"
  },
  "addons": {
    "ember-data": "2.16.3",
    "ember-cli-mirage": "0.4.4"
  }
}

[Gaurav0]

Yes. I generally put as much as possible in the default twiddle.json on purpose so people can see how to use it. The only two options suported right now are shown.

I use "version" to help ensure that old twiddles continue to work, since people rarely update them.

Dependencies are directly imported, similar to app.import in ember-cli Addons are built by the backend first, similar to including the addon in your package.json.

[MelSumner]

@MelSumner maybe you can consider finding someone to help write it? I'll be happy to work with them.

@Gaurav0 sure! Do we have a quest issue for this?

[Gaurav0]

Do you need one? What does a quest issue look like?

[Gaurav0]

relevant: #634