[DOC] Provide a better doc than the actual messy README

[huafu]

The README is pretty much complete, but it's messy. I'd love to have the demo being on the index route, but with Twitter bootstrap theme for example and a menu showing help too, in which there would be a complete, readable documentation with TOC.

I can totally do the coding and integration of bootstrap, but I am not a native English speaker and I am very bad documentation writer when it's about non deep tech doc in the middle of the code ;-)

Anyone willing to help? Please do not drop a PR just right now like this, I want to talk about it first.

[davidpaulsson]

Sure I'd like to help. English isn't my official language either, but I think we could come up with something :)

I'm a designer/front-end guy who don't have much love for bootstrap (everything looks the same), let's build something custom for this superb addon. And the project needs a logo :)

[huafu]

Wow that will be nice if you could help on that. I am actually creating a page for myself with bootstrap (yeah no time for design and I am a shit designer) where I'll link and explain briefly all my addons and work.

But if you help on this it'll be great to do in the test/dummy folder as a part of the demo app and so repo (I'll add it to the .npmignore if not yet there.

If you want to start, move whatever is in application inside another route, same for the controller to kinda backup them for now, and maybe we can start on a site with intro, doc, demo and about screens.

[huafu]

I am a shit designer = I am not designer and anytime I try to design something it looks old and ugly lol

[davidpaulsson]

Hehe, how about I start with some wire frames and we can take it from there? I have little new born at home, but I'll try to make some time this weekend.

[davidpaulsson]

This is just an example, and it'll probably look nothing like this. But it's in this direction you'd like to take it, right? A compete "website" describing the plugin? Yes? http://www.listjs.com/

[huafu]

yeah kinda, but it doesn't have to be too big, for now just intro, demo and short doc page.

(Don't worry mine is 5 months old here so I know what you mean about the time)

[davidpaulsson]

Hey again, so here's a very quick mockup/wireframe describing what I'm thinking. It's intentionally very Ember-ish with the colors and the Tomster etc.

I have no thought on the actual content of these two images, just the general layout and "feel" and then probably the design will grow as the documentation gets written. Thoughts?

[huafu]

You rocks! One thing I am unsure is "are we allowed to copy ember website design"? I'll send an email to Lea about that, she is responsible of that stuff at Ember. And yeah I agree that if we can, let's stick to their design!

[davidpaulsson]

Hehe, thx…

I think the biggest issue is if one can use the tomster like that :) it's definitely questionable. But I figured it's quite obvious that it's giving the proper attribution to the original Ember project.

As for the design it's just the colors that's the same, so that shouldn't be an issue.

I can do a quick test where it feels more Google Maps than Ember though?

Either way I think the design should "feel" Ember or Google Maps, since that's what it's about after all.

[huafu]

If it's quick test, yes, but I'd prefer half ember half google if that is possible. Tho this looks nice.

Btw, i added an icon.png on the root of the repo, feel free to update it, it is used on my newly done website http://huafu.github.io ;-)

[MrJadaml]

Any documentation for initial CLI implementation would be greatly appreciated.

[ohizkiya]

If you guys come up with an initial cut of the documentation, I would be glad to look it over and ensure it reads well.

[sbsurf]

I can fill in some blanks eventually, as well. Once I get all my issues resolved and feel comfortable using all the features I need. Plus my current gig is up at the end of this week, so I should have some extra time.

[wifelette]

Heya friends—

While it looks nice, this is unfortunately exactly the sort of thing the Trademark and rules expressly prohibit :/

As a passing user if I saw a site like this I would definitely assume this was an official Ember owned and maintained project.

The trick is to design something that looks like it fits well with the Ember look and feel, but that is clearly something else. Both the logo and Tomster also cannot be used in this way, for the same reasons expressed above (in general, the Tomster is even less free to use, since it's not just the project name, but the mascot).

Sorry to be the one with the frustrating news. It's important that we protect Ember from any unofficial uses, so that we have a leg to stand on when people try to do actually bad things with our name/likeness. It's the nature of the US laws on the matter.

Other ideas in the queue, I hope?

[huafu]

@wifelette yeah I was worried about that, so thanks for the clarification. I'd anyway get you preview it once we have a first version before deploying.

Other than that, I am preparing, but slowly, a list of things that MUST be explained well, as well as some small examples for each issue. Reading the list of all issues helps finding out what are the things to put together. Unfortunately, as I said, I have not much time those days :-/

(side not for you Leah, not related to this addon. Is that ok for me to use the logo as I did there? Also for the icons of most addons? If not I am going to change it asap)

[davidpaulsson]

ok! then it's cleared up and will be modified.

[huafu]

I think we should begin by creating some simple wiki pages here ;-)

[huafu]

Here we go for an index, what is missing or should be changed? https://github.com/huafu/ember-google-map/wiki

[huafu]

I strongly updated the wiki, missing only the example and about sections there, so we have our content, and we could use the github API coupled with my ember-marked component on the future website to use the wiki directly as our content.

As soon as I'll be done with the remaining wiki pages, I'll close this issue. While we can continue to discuss about the site here, I prefer to have it closed since the docs will then be done.

[ohizkiya]

I just finished going through every page of the wiki that exists thus far and editing for clarity / readability.

There are remaining questions and comments that I have -- but I'll post those when I have more time.

[huafu]

Cool thank you very much!

[ohizkiya]

Here are a few question I had. I think we can use the answers to these to make the documentation clearer.

1) The installation guide states: "You can also find instructions on how to install Handlebars 2 here, if required." Under what scenarios would Handlebars 2 be required? Should we make a note of these?

2) The Lazy Loading section states: "If you are using lazy-loading then you'll need to load the Google Maps library in each route (or parent, sub-parent, ... route) that has a template using the {{google-map}} component." I'm not sure I properly understood the bit in parenthesis. Does it mean to say that if lazy loading is enabled then one must load the google map library in any route that is a parent of the route in which {{google-map}} is used?

3) Support is provided for Google Maps options that are no explicitly implemented in the add-on using gopt_option_name. Do options set in this manner have two way binding enabled or are they only available to be set on initialization?

4) The Available Controllers section states: "The polyline-path and polygon-path controllers each extend Ember.ArrayController so that you can handle their paths separately." I'm not sure I understood what "so that you can handle their paths separately" means. Does it mean that these controllers exist so that you can customize the behavior of an entire path? What would be an example customization where this functionality would come in handy?

5) In the events section, name is defined as "the event name if prependis true or if it's undefined and it's not an action." I didn't quite follow the cases that this is trying to lay out. Name will be the event name if prepend is true, undefined if it's not an action and ??? if prepend is false?

Apologies for the long list of questions -- if you can give some guidance on each of these, I can go back and edit explanations into the wiki. Definitely feel that polishing the documentation (thanks for your hard work to get it to the point where it thoroughly covers things as of now) will contribute to this add-on's popularity.

[huafu]

First of all, I reviewed all your changes, thanks A LOT (added a special thanks in the About section)

When you update a title (prepended with any number of #), please be sure to then update the links in other pages referencing it (for example I've fixed the TOC and Home pages for Main {{google-map}} component which has been renamed to The main... => #main-google... became #the-main-google...)

1. Yes, the thing is that when you come from Ember < 1.9 and upgrade it then needs the htmlbars compiler instead of handlebars and needs handlebars to be upgraded to >= 2.0
2. What I meant there is that if you have a user.travels.map route, you'll need to load the map in user.travels.map route, OR in users.travels route OR in users route. So that if you have maps in users.travels.map, users.travel.all, ... you could load the map with the helper only in user.travels route instead of all sub-routes needing it.
3. No, they are only set upon initialisation, as some other stuff that I wrote (read-only after initialization), and it's google making it read-only.
4. You could for example listen for changes in the path and do some stuff related to it, or round values, etc...

5. The events can do 2 things: either send an ember action, or call a method/function. The target by default is the controller holding the google-map component, else if it's given it'll be used to either target.send(<action>, ..) or target.method(...). For the prepend:

   • in case of an action:
     • prepend not set or set to false: arguments will be: <ember-object-where-googleEvents-defined>, <event>
     • prependset to true: arguments will be: <event-name>, <ember-object-where-googleEvents-defined>, <event>
   • in case of a method/function:
     • prepend not set or set to true: arguments will be: <event-name>, <ember-object-where-googleEvents-defined>, <event>
     • prepend set to false: arguments will be: <ember-object-where-googleEvents-defined>, <event>

   The latest is the opposite, because one would more likely define a specific action per event whereas a common method/function to handle many events and then the event name would be handy

Thanks again for your great contribution!

[ohizkiya]

In the future I'll be sure to update the links when changing a title.

I went ahead and placed placed notes/clarifications in the appropriate places based on your comments above.

Also, do you think we should update the description of the addon in NPM so that it's clear wiki is a link and to at least give an executive summary?

[huafu]

That would be a great idea. Anyway, the short desc in npm comes with packages.json, in the description, and the long description is just the readme, so PR if you have time, I have too many projects and addons to handle lol