If I may be permitted to chime in here with my $0.02, some observations as an Akka bootstrapper:
Everybody has their own learning style -- some people I know can read even a fairly dense API spec and start writing code. Personally, I need to get started on a problem-solving basis so in the early days: I'm more of a monkey-see-monkey-do person, taking existing code and trying to shape it to fit my particular use-case. For learners like me some of the examples of code are a little terse -- they don't show enough context. Looking at them in retrospect, they are adequate, but in prospect they can be a little obscure. While I haven't yet the skill to construct them myself (I'm an akka hobbyist, not a professional), what might be useful is to draw the code examples from a working code-base so they can be seen in the context of a project the student can build and run. Many of the official Java tutorials do this reasonably well. I know there are some good Activator samples available, but they don't correspond to the examples in the Akka documentation and their internal documentation can be rather sparse. The Activator samples, once you understand them, are very clever, but the cleverness can obscure the basics. An analogy: I love a good proof in mathematics and can appreciate the elegance and beauty therein, but understanding a proof and gleaning generalizable skill from it can be two different things. What makes the proof a good learning tool (for people like me) is an explanation of the motivation and methods that went into its derivation. Something similar for code samples would be very helpful. Also, in some of the examples it can be a little hard to distinguish between those aspects of the code that are essential to the point being made and those that are not but nonetheless required to make compilable code -- detailed explanations of the examples would go a long way to enhancing their illustrative value. I feel bad suggesting work for others to do, and my suggestions might be out of the scope of what's intended for the documentation, but I hope you can sympathize with my position: I'm not yet sufficiently knowledgable to be writing books or tutorials, and offer my comments in response to your interest in improving the Akka experience for novices. Thank you for your patience in reading this. Regards, Mike On Thu, Jan 19, 2017 at 3:07 PM, Josep Prat <[email protected]> wrote: > As former participant of that course, I think they would be a great > addition to the current documentation assets. But I'm still interested in > what the OP thinks it would improve a freshman experience. > > Best, > Josep > > On Thursday, January 19, 2017 at 8:59:53 PM UTC+1, rkuhn wrote: >> >> While “terrible” is pretty strong wording I think it is fair to say that >> Akka has very good reference documentation but its initial learning >> experience can be improved. Would it help if some of the video courses were >> available (for free, of course) that were part of Principles of Reactive >> Programming? >> >> Regards, Roland >> >> Sent from my iPhone >> >> On 19 Jan 2017, at 20:41, Josep Prat <[email protected]> wrote: >> >> Welcome to Akka! >> As Lutz already said, I would recommend "Akka in Action". The only catch >> is that the code is mainly in Scala. >> I have a question though, why do you say the official documentation is >> terrible? I personally find Akka docs quite good. What would you change/add >> to the current ones? >> >> Best, >> Josep >> >> On Thursday, January 19, 2017 at 2:34:29 PM UTC+1, Qian Liu wrote: >>> >>> Hello everybody, >>> >>> I'm new-comer to Akka, the official documents for Akka learning is >>> terrible. not very well structured. Beginners will soon feel lost with >>> these official documents. Do you know any better resources to learn? I'm a >>> java developer. >>> >>> Thanks a lot. >>> >>> Best regards, >>> >>> Qian Liu >>> >> -- >> >>>>>>>>>> Read the docs: http://akka.io/docs/ >> >>>>>>>>>> Check the FAQ: http://doc.akka.io/docs/akka/c >> urrent/additional/faq.html >> >>>>>>>>>> Search the archives: https://groups.google.com/group/akka-user >> --- >> You received this message because you are subscribed to the Google Groups >> "Akka User List" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to [email protected]. >> To post to this group, send email to [email protected]. >> Visit this group at https://groups.google.com/group/akka-user. >> For more options, visit https://groups.google.com/d/optout. >> >> -- > >>>>>>>>>> Read the docs: http://akka.io/docs/ > >>>>>>>>>> Check the FAQ: http://doc.akka.io/docs/akka/ > current/additional/faq.html > >>>>>>>>>> Search the archives: https://groups.google.com/group/akka-user > --- > You received this message because you are subscribed to the Google Groups > "Akka User List" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at https://groups.google.com/group/akka-user. > For more options, visit https://groups.google.com/d/optout. > -- >>>>>>>>>> Read the docs: http://akka.io/docs/ >>>>>>>>>> Check the FAQ: >>>>>>>>>> http://doc.akka.io/docs/akka/current/additional/faq.html >>>>>>>>>> Search the archives: https://groups.google.com/group/akka-user --- You received this message because you are subscribed to the Google Groups "Akka User List" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/akka-user. For more options, visit https://groups.google.com/d/optout.
