Inspiring documentation

Hi guys,

we are paying attention to docs lately which is a wonderful thing.

Here is some inspiring docs I've found:

http://emberjs.com/guides/

What's so good about them?

How didactic its pattern is:

1. gracefully introduction

2. each topic address increasingly important questions 

3. answers first how to start, then more and more details.

4. Validation. We know it worked in educating their community.

Lets take a deep breath and a good look into them :)

I think the best question we can ask is:

What are the minimum topics we need to cover in our docs to make a newcomer feel she/he can:

1. start a new amber project

2. develop some code

3. deploy

Your input? what do you think they might need?

Or... are you an Amber lurker? please we need to hear your input! help us help you!

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.

Thank you for testing, Tim

I have updated https://github.com/hhzl/amber-kickstart/blob/master/README.md
according to your feedback.

Some more comments below.

--Hannes

On 4/11/14, Tim Mackinnon <[hidden email]> wrote:

Hey thanks - I took a moment to follow that, and voila, it did indeed
install... which is a great first step.

I did notice one warning (but I think its ok right?)

bower                          no-json No bower.json file to save to, use
bower init to create one

I do not know if this is important here or not, Herby?

I think the initial paragraph should say a bit more about what Amber is
(e.g. after "A starting point for a frontend with Amber." - maybe explain
what Amber is beyond superb, and link to the best place to read more about
amber...

Done.

The rest of the instructions were very clear (thanks).

Step 7. I think should reference MyPackage not SamplePackage right?

Done.

For the Notes - I wasn't clear where you rename (is that in Helios? or in a
text editor?

I assume Helios - which I know what that is from lurking but

many wouldn't.

No, I did it in a text editor.

The challenge is to make sure the package gets loaded when you refresh
the page. This is indicated in the index.html file.

I feel that there are some additional steps that would give people a flavour
of what's possible (and maybe these are in another tutorial?). I think the
following might pique interest:

8. Explain how to navigate the code and make a simple live change? Having
said this - I thought I changed Counter to start with an initial value of 10
by changing the initialise method - however now it doesn't seem to take
notice of my change (although I swear it did when I first did that).

- Save the method and
- Commit the package CTRL-SPACE k

Do I

have to do something special beyond - save method?

9. Explain how to run Unit Tests? I can't seem to do this - it does nothing
when you try to open an SUnit tab - I get a No Tools are Open page and
clicking on Test Runner does nothing? the same applies to clicking on the
Help button as well.

The same applies for me. I do not know if this is a defect of Amber
0.12.4 or a problem of the

   https://github.com/hhzl/amber-kickstart

setup

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.

Hey - that's very good!

I've worked out why my changes were't appearing - and maybe its something that could called out.

When you get the helios browser and make a change - when you save a method it is "live applied" (which is something that most dev's won't expect). So when you change to your page - you don't need to hit refresh - the next counter you create will have the new value. Crucially - if you do refresh your page there are two things that you hint at - that you need to understand. If you refresh but haven't committed your package - you will lose your changes (similar to if you make changes in Firebug or Chrome dev tools - so I think people get that). The second part to this however (which is what caught me out) - you are prompted to navigate away from your page in Helios. If you don't do this (thinking to yourself - but I don't want to lose my changes yet) - you will now have a browser that I guess is pointing to an orphaned code model. Making changes in this "orphaned" browser means that none of your changes will appear live (they are changing a code model you can't see). I would say - there needs to be a brief overview of what is happening so people understand how they should use the tools.

Alongside this - there is another really cool step that should be called out - "live debugging". So I would also mention to people - try putting "self halt" in the "increase" method. And then try stepping through the code.

I think those few things - really show a light bulb in people's heads. Certainly the guys in my office were astounded.

Maybe Step 3 in the docs should read like the following:

1. As an example you might want to try changing the initial counter value to 10 in the initialze method of the Counter class the Examples package. After you have saved the method, you will now get a counter which starts with 10 when you click on the counter button on your page. You don't have to reload the page to see this change, it's performed live in your page environment. However, if you want this change to persist across page reloads, you need to perform an extra step, and press "Commit Package" to save your package changes to the file system (the Helios code browser indicates this by showing a red Package icon). You will find the new version of the Examples package in the subfolder bower_components/amber/src. 
2. Another interesting difference in Amber, is that you have access to a live page debugger. If you add the line "self halt." at the top of the increase method, save the method and then press the ++ button in your page - you will get a stepping debugger where you can step through the code that increases the count value. This opens the possibility to really understand how your program works. 

By the way - in that step 2 - I notice that if I try and inspect the Count value and then press continue in the debugger, it seems to corrupt something as I get "X does no understand contents" -  I think this must be a bug. It would be good to also explain how you can change the code in the debugger to emphasise the live coding difference.

Anyway - thanks for your help in getting me hooked again!

Tim

On 11 Apr 2014, at 17:38, "H. Hirzel" <[hidden email]> wrote:

Thank you for testing, Tim

I have updated https://github.com/hhzl/amber-kickstart/blob/master/README.md
according to your feedback.

Some more comments below.

--Hannes

On 4/11/14, Tim Mackinnon <[hidden email]> wrote:

Hey thanks - I took a moment to follow that, and voila, it did indeed
install... which is a great first step.

I did notice one warning (but I think its ok right?)

bower                          no-json No bower.json file to save to, use
bower init to create one

I do not know if this is important here or not, Herby?

I think the initial paragraph should say a bit more about what Amber is
(e.g. after "A starting point for a frontend with Amber." - maybe explain
what Amber is beyond superb, and link to the best place to read more about
amber...

Done.

The rest of the instructions were very clear (thanks).

Step 7. I think should reference MyPackage not SamplePackage right?

Done.

For the Notes - I wasn't clear where you rename (is that in Helios? or in a
text editor?

I assume Helios - which I know what that is from lurking but

many wouldn't.

No, I did it in a text editor.

The challenge is to make sure the package gets loaded when you refresh
the page. This is indicated in the index.html file.

I feel that there are some additional steps that would give people a flavour
of what's possible (and maybe these are in another tutorial?). I think the
following might pique interest:

8. Explain how to navigate the code and make a simple live change? Having
said this - I thought I changed Counter to start with an initial value of 10
by changing the initialise method - however now it doesn't seem to take
notice of my change (although I swear it did when I first did that).

- Save the method and
- Commit the package CTRL-SPACE k

Do I

have to do something special beyond - save method?

9. Explain how to run Unit Tests? I can't seem to do this - it does nothing
when you try to open an SUnit tab - I get a No Tools are Open page and
clicking on Test Runner does nothing? the same applies to clicking on the
Help button as well.

The same applies for me. I do not know if this is a defect of Amber
0.12.4 or a problem of the

   https://github.com/hhzl/amber-kickstart

setup

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.